Tool descriptions are generic and under 20 characters below ideal baseline. Examples: 'Semantic search tool for knowledge base queries' (50 chars), 'Hybrid search combining semantic and keyword matching' (54 chars), 'Convert PDF documents to structured format' (41 chars). LLM-optimized descriptions should be 50-200 chars with explicit WHEN/WHY guidance.
Input parameter details are not visible in the provided schema data. Tool registry loads Pydantic models from src/models/schemas, but the actual schema definitions (type constraints, min/max, enums, validation rules) are NOT shown in the code excerpt. Cannot verify parameter descriptions, type declarations, or validation rules.
Expand tool descriptions to 50-200 chars with explicit WHEN/WHY guidance. Example: 'semantic_search' should become 'Search knowledge base using semantic vector similarity. Use when you need conceptually similar documents, not exact keyword matches. Faster than hybrid_search but less precise.'
Add detailed parameter descriptions to Pydantic models in src/models/schemas. For 'query' params, specify: format (free text? regex? structured?), min/max length, example values, when to use this tool vs peers.
Document output schemas for every tool. Add to tool_registry.py output_schema field or a docstring detailing returned fields, types, and whether pagination is supported.
Consolidate overlapping search tools (semantic_search, hybrid_search, knowledge_search, pattern_search) into a single well-named search tool with a 'search_type' enum parameter (semantic|hybrid|keyword|pattern) and clear descriptions of when each mode is optimal.
Add explicit side-effect statements to WRITE tool descriptions. Example: knowledge_refine should say 'This modifies the knowledge base. Not idempotent, repeated calls with identical input may produce different results.'
Add pagination support to list-returning tools. Include optional params: limit (default 20, max 100), offset (default 0). Return paginated_results with fields: items[], total_count, next_cursor.
Add error handling guidance to tool descriptions and implement structured error responses. Example: 'If query is empty, returns error code INVALID_INPUT. If backend is unavailable, returns RETRYABLE. Recommend exponential backoff with jitter for RETRYABLE errors.'
Overlapping search tools cause composition ambiguity. semantic_search, hybrid_search, knowledge_search, and pattern_search all accept a 'query' parameter and perform discovery. LLM must reason about which to use, wasting tokens and risking wrong tool selection. Pattern suggests consolidating into a single well-named tool or making distinctions explicit (e.g., semantic_search for embeddings, pattern_search for regex, keyword_search for text).
WRITE tools lack explicit side-effect documentation. knowledge_refine, a2a_send_message, a2a_cancel_task, generate_taxonomy, enrich_book_metadata, batch_enrich_metadata, and enhance_guideline all modify state but descriptions do not say 'this creates/updates/deletes/sends'. Agents need to know which calls are idempotent and which have irreversible consequences (pattern:command-tool).
Output schemas are not documented in the provided code. LLM cannot determine what fields are returned, required for downstream tool chaining. Pattern requires documenting output schema so agents can extract IDs needed for follow-up calls (e.g., does semantic_search return document_id, relevance_score, source?).
No pagination support visible. Tools like semantic_search, hybrid_search, and audit_corpus_search likely return lists but no limit, offset, page_size, or next_cursor parameters are shown. Pattern:paginated-result requires accepting pagination params and returning total counts to prevent context window exhaustion.
No visible error handling or recovery guidance. Tool definitions lack details on how failures are reported, what retry guidance is offered, or how LLMs should react to failures. Pattern:recovery-guide requires error responses to guide the next step.
No visible permission gates or scope declarations. Tool registry loads tier-based access (bronze/silver/gold/enterprise) but does not show scope declarations (e.g., 'read:knowledge', 'write:audit'). Pattern:permission-gate and pattern:scope-declaration require each tool to declare what permissions it requires and to verify the caller has authority.
Declare permission scopes for each tool. Add scopes field to ToolDefinition: e.g., a2a_send_message requires scope 'write:agent-communication'. Document scopes in tool_registry.py or a separate SCOPES manifest.
Add recovery guidance to error responses. Instead of raw exception, return: {"error": "User not found", "suggestion": "Try search_users() with partial name first", "retryable": false}.
Implement confirmation step for destructive operations. If a tool deletes, sends, or publishes, add an optional 'dry_run' parameter (default false) or require explicit 'confirm' parameter set to the resource ID being destroyed.
Add missing Pydantic input model schema data to the source. The excerpt cuts off mid-file in src/tool_registry.py. Verify ALL 37 tools have explicit input_model entries mapped to concrete Pydantic classes with type constraints and field descriptions.