Tool formatting¶

Tool-related utilities for Klea

File: klea_utils/tools.py

klea_utils.tools.build_tool_description(t: mcp.types.Tool) → str[source]¶

Build the compact LLM-facing description for an MCP tool.

Used to populate klea_utils.mcp.schemas.ToolInfo.description so the tool picker’s prompt stays small as more tools are added.

Klea expects MCP tool descriptions to follow the docstring-first convention (see docs/concepts/mcp.rst, “Tool description length and style”): the LLM-facing description is the opening text block of the function docstring, written as a one-sentence summary followed by “Use when:” / “Do not use for:” bullet sections and a single example line, bounded to roughly 100-250 tokens. Anthropic recommends at least 3-4 sentences covering what a tool does and when it should (and should not) be used; opencode keeps its tool descriptions to roughly 100-600 tokens with a one-line summary first.

Parameter descriptions are given in a Google-style Args: section that fastmcp parses into the schema, so they must not be repeated in the description. MCP servers must not set the tool description to the raw full docstring (see neuroml_mcp.utils.register_tools), otherwise the prompt carries duplicated Args:/Returns: prose in both the description and the compact parameter list built here.

klea_utils.tools.clean_tool_meta(meta: dict[str, Any] | None) → dict[str, Any] | None[source]¶

Drop developer tags from tool metadata before storing it.

FastMCP populates meta with {"fastmcp": {"tags": [...]}}; the tags are mostly developer labels (e.g. testing) that are not used by the tool picker, so they are stripped to keep stored metadata lean.

klea_utils.tools.textualize_tool_results(tool_results: list[fastmcp.client.client.CallToolResult]) → str[source]¶

Format tool call results as LLM-ready text for use in prompt context.

Tool return values are typically JSON-structured data (dicts, lists) which LLMs handle naturally. We wrap them in markdown code blocks for clear separation from surrounding prompt text.

Parameters:: tool_results – List of tool call results
Returns:: Formatted string suitable for inclusion in an LLM prompt