semantic_search

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It doesn't disclose read-only semantics, whether it returns ranked/relevance-ordered results, whether the search depends on an index that must be pre-built, or how it handles empty/no-match queries. For a search tool that presumably reads data, it should at least clarify it's non-destructive and what the result format looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one short sentence with minimal waste, appropriate for a straightforward search tool. It's front-loaded and efficient, though it sacrifices usefulness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 5 parameters, an enum-driven type system, conditional dependencies (filePath/projectPath required for code type), and no output schema or annotations. Given this complexity, the one-sentence description is insufficient. It should explain the type-dependent behaviors, clarify the limit default behavior, and describe what a semantic search returns. A moderately complex tool with zero annotations needs substantially more context than one sentence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. However, the description adds nothing meaningful beyond the schema, particularly for 'filePath' and 'projectPath' which are marked 'required for code type' in the schema but not contextualized further. One area where the description could add value is explaining how 'type' interacts with other parameters (e.g., which params matter for each type), but it doesn't.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Unified semantic search across different content types,' which names the verb (search) and resource (content types) but is quite generic. It doesn't specify what is searched (workflows, templates, code) in the description itself, though the schema enum reveals this. It partially distinguishes from siblings like analyze_code and list_workflows, but the purpose is stated vaguely without naming the specific content types or result behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives like list_workflows, get_workflow, or analyze_code. It doesn't explain when semantic search is preferred over exact/explicit lookup, nor does it state exclusions or when not to use it. The keyword 'unified' hints at cross-type capability, but there's no explicit when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.