search_graph

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

With no annotations, the description carries the transparency burden. It discloses ranking behavior ('most relevant'), scope over structural node labels, return contents (kind, source location, connectivity degree), and a hard dependency on index_graph. It does not mention error behavior if the graph is missing, but for a search tool this is reasonably transparent.

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 key behavior and prerequisite are front-loaded, followed by a compact Args/Returns breakdown. Every sentence adds information; the only minor redundancy is restating the default limit already present in the schema.

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 description is sufficient for a simple 3-parameter search tool: prerequisite, query semantics, limit, and return summary are covered, and an output schema exists for details. It could be more complete by stating behavior when index_graph has not been run and how results are ordered, but nothing critical is missing.

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 Args section must carry the semantic weight, and it does. It explains query with concrete examples, path as the codebase root, and limit as maximum results with default. This is exactly the guidance an agent needs beyond the property titles.

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 opening line names a specific verb ('search'), a specific resource ('knowledge graph'), and a query criterion, and the next sentence narrows the target to node labels (function/class/file names), which distinguishes it from sibling search_code and graph_neighbors. This is enough for an agent to know what the tool matches and returns without opening the schema.

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 explicitly states the prerequisite ('codebase graph must be built first with index_graph') and gives query style examples. It does not name when-not-to-use alternatives, but it provides clear context about keyword-inside-labels vs code search, so an agent can infer the right situation.

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