find_callees_recursive

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

Since no annotations are provided, the description carries full burden for behavioral disclosure. It describes the transitive BFS search, depth parameter (default 5), deduplication by shortest distance, and the requirement for the reference index. This gives a complete picture of the tool's behavior.

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 concise and well-structured. It starts with a direct usage recommendation, then explains the tool's function, use case, and output characteristics in a few sentences. Every sentence serves a purpose without redundancy.

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?

Given the tool's moderate complexity, the description covers prerequisites, behavior, alternatives, and output structure. Since the tool has an output schema (not shown, but indicated), explaining return values is not necessary. The description is complete for an agent to decide when and how to invoke it.

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?

With 100% schema coverage, the baseline is 3. The description adds value by explaining the transitive nature, BFS depth semantics, and deduplication logic beyond what the schema's parameter descriptions provide. However, it doesn't elaborate on the `limit` or `project_root` parameters beyond schema, so improvement is possible.

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 the tool performs transitive C/C++ callee analysis using libclang's call graph including function-pointer edges. It distinguishes itself from the alternative `ctx_callgraph(action='callees')` and the sibling `get_symbol_context` for direct callees, making the purpose unambiguous.

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 advises 'USE INSTEAD OF ctx_callgraph(action="callees")' and contrasts with `get_symbol_context` for direct callees. It specifies the use case (dependency analysis) and mentions the prerequisite of having the reference index, providing clear guidance on when and how to use the tool.

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