Three tools with action-verb names and basic schemas, but missing critical documentation and output schema specs. Tool names follow verb_noun convention (search, expand_cluster, find_ticket_dependencies). Descriptions are present but generic (10-150 chars, below baseline 194 chars). Input parameters have type definitions and brief descriptions, but lack constraint documentation (enums, ranges, format specs). No output schemas visible in the provided code, critical gap. Error handling and recovery guidance absent. Parameters are minimal (2-3 per tool) but lack specificity about valid values and ranges. No tool annotations (readOnly hints) despite all three being READ_ONLY operations. Schemas are inferred from the input dict structure but not fully formalized in JSON Schema notation with type definitions explicitly shown.

• Add explicit JSON Schema output definitions for each tool. Document fields returned by search (e.g. id, title, content, score, project_id), expand_cluster (id, related_ids, cluster_size), and find_ticket_dependencies (ticket_key, dependencies, depth, blocked_by, blocks). Include field types and when they are null.
• Expand tool descriptions to 100-200 chars. Example: 'search: Retrieve documents from the vector database using semantic similarity to your query. Returns up to limit ranked results with relevance scores. Use for content discovery when you need background info.' Include WHEN to use it vs alternatives.
• Add parameter constraints in descriptions. Example: 'limit (integer): Maximum number of results to return. Default 20, range 1-100. Higher values increase latency.' 'depth (integer): Traversal depth for cluster expansion. Range 1-5. Higher values risk exponential growth; start low.'
• Add readOnlyHint=true to all three tools in their schema registration. All three are read-only queries with no side effects. Clients can cache results and retry safely.
• Add error recovery hints. Example for search: 'If no results found, try: (1) broaden query keywords, (2) check project_id exists, (3) verify embeddings indexed.' Similar for expand_cluster and find_ticket_dependencies.
• Document parameter formats explicitly. 'ticket_key (string): Jira issue key in format PROJECT-NUM (e.g. PROJ-123). Case-sensitive.' 'project_id (string): UUID of the project (e.g. 550e8400-e29b-41d4-a716-446655440000).'

Inferred effective spec: 2026-07-28+.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry