Generic factory-generated tool names (<name> placeholders) prevent LLMs from understanding which tool to invoke. Names like 'consult_<name>', 'clear_<name>_history', '<name>_status' are not actionable, the LLM cannot select a tool whose name is a template variable.
Most tool descriptions are too generic or too short (under 20 chars). 'Read contents of a file', 'Write content to a file', 'List contents of a directory' lack LLM-optimized context about WHEN to use each tool and what distinguishes them. No guidance on prerequisites, error cases, or chaining with other tools.
No output schemas documented for ANY tool. LLMs cannot plan downstream calls or extract required fields (e.g., does read_file return {content: string, size: int, encoding: string}?). This forces agents to guess at response structure.
Recommendations
Replace all template-variable tool names (<name> placeholders) with concrete, fully-qualified names. E.g., 'consult_claude' and 'consult_gemini' instead of 'consult_<name>'. Tool names must be actionable for the LLM.
Expand every tool description to 50-200 characters explaining WHAT it does, WHEN to use it, and HOW it differs from related tools. Example: 'Read a file from the filesystem. Use this to examine code, config, or logs. For binary files, encoding is auto-detected. Returns full content (no truncation) up to 10MB.'
Document the output schema for every tool. Use a structured format: '{"type": "object", "properties": {...}, "required": [...]}' Example for read_file: '{"content": {"type": "string", "description": "File contents as UTF-8"}, "size_bytes": {"type": "integer"}, "encoding": {"type": "string"}}'
Add parameter descriptions to ALL inputs, including optional ones with defaults. Example for list_directory: 'path (string, default="."): The directory to list. Absolute paths are expanded; relative paths are resolved from the current working directory.'
For array parameters (location, rotation in Blender tools), specify length, element type, and semantic meaning. Example: 'location [number, number, number]: Camera position in Blender world coordinates [X, Y, Z] in meters.'
Constrain glob patterns in search_files with examples. Example: 'pattern (string, required): A glob pattern like *.py for all Python files, src/**/*.rs for Rust files recursively, or test_*.py for test modules.'
run_command tool has a DANGEROUS default timeout (30 seconds) and no error recovery guidance. Description states it does not support pipes/redirection, but does not explain what TO DO if the user needs those features. No mention of capturing stderr vs stdout or exit codes.
list_directory parameter 'path' has a default value '.' but no description. This violates the rule that EVERY parameter must have a description explaining what it controls. Agents cannot reason about path defaults without explicit guidance.
search_files 'pattern' parameter accepts a glob but the description does NOT specify the glob syntax (e.g., * for anything, ? for single char). Agents will guess and produce invalid patterns.
Blender camera tools (setup_camera, add_camera_track, create_camera_path) accept arrays for 'location' and 'rotation' but do NOT specify the array length, element types, or expected coordinate system (e.g., [x, y, z] in Blender units). Parameter descriptions are vague and will lead to malformed inputs.
No error handling patterns visible. Tools like run_command and web_search offer no guidance on retryability, user-fixable errors, or recovery steps. Agents will not know how to respond to timeouts, network errors, or invalid inputs.
Tools are scattered across multiple files (gemini_tool_executor.py, mcp_core_rust crates, mcp_blender scripts) with no unified registration or server entrypoint visible. It is unclear whether this is a single MCP server or a collection of independent tool modules.
No pagination support visible for list_directory or search_files, which could return hundreds of results. Without limit/offset/page params and total_count in responses, large result sets will exhaust the context window.
consult_<name> tool has a 'comparison_mode' boolean parameter defaulting to true, but the description does NOT explain what comparison_mode does or what 'previous Claude response' means. Ambiguous parameter semantics invite misuse.
setup_camera requires 'camera_name' but it is unclear whether the tool creates the camera or assumes it already exists in the Blender scene. Description must state this upfront to avoid errors when the agent passes a non-existent camera name.
setup_camera
Add error recovery guidance to run_command and web_search. Example: 'If the command times out (>300s), it is likely hung. Try breaking the command into smaller steps. If web_search returns 0 results, try a simpler query or different keywords.'
Centralize tool registration into a single MCP server entry point. Define all tools in one manifest or factory so clients can discover the full set. Include a 'tool discovery' endpoint or resource that lists available tools with their current descriptions.
Add pagination to list_directory and search_files. Include optional 'limit' (default 20, max 100) and 'offset' (default 0) parameters. Return {"items": [...], "total": 1500, "limit": 20, "offset": 0} so agents know when to fetch the next page.
Clarify what 'comparison_mode' means in consult_<name>. Either expand the description or replace the boolean with an enum like 'comparison: none | previous_response | previous_and_current' with clear semantics.
For setup_camera, explicitly state: 'Creates or updates a camera named camera_name in the Blender scene. If the camera does not exist, it is created. If it exists, its location, rotation, and focal length are updated.' This prevents the agent from assuming a missing camera is an error.
Add security and rate-limit guidance. Example: 'run_command: Executes as the current user. Sanitize all user inputs to prevent command injection. Maximum 10 commands per minute per agent session.'
Document idempotency. Which tools are safe to retry? (read_file, list_directory, web_search are idempotent; write_file, run_command, setup_camera are not.) This guides agent retry logic.
Return IDs and references needed for chaining. If web_search returns a URL, also return a summary so the agent can decide whether to click it. If list_directory returns file names, also return file sizes and modification times so the agent can rank by recency.