search_semantic

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

With no annotations provided, the description carries full burden. It explains the hybrid approach using FTS5, vector similarity, and RRF. It also notes the need for pre-computed embeddings. It does not disclose failure modes or fallback behavior if embeddings are missing, but overall provides good behavioral insight.

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 well-organized with paragraphs, an example, and a prerequisite note. It is efficient but could be slightly tighter. Every sentence adds value, though the two-line example could be integrated.

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?

An output schema exists (unseen), so return values are covered. The description covers the core use case, method, and prerequisites. However, it lacks guidance on excluded directories and output formatting, and does not address edge cases like missing embeddings. Still, it is generally complete.

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 0%, so the description must compensate. It meaningfully describes three of five parameters (repo_path, query, limit) but omits exclude_dirs and output_format. The described parameters add clear semantic value beyond the schema, but the missing ones are a gap.

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 clearly states it performs hybrid semantic + structural search across all symbols in a codebase. It distinguishes itself from exact name matching with a vivid example, making the purpose unmistakable.

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 explains when to use this tool (to find symbols by meaning) and provides a prerequisite (run `python3 -m tempograph <repo> --embed` first). However, it does not contrast with sibling tools nor specify conditions where this tool is not suitable.

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