trace_callees

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

With no annotations provided, the description must disclose behavior itself. It does so by explaining the default filtering of 'unresolved std/common-method noise' and how to opt back in via the include array. This gives actionable behavioral context beyond a simple read query. It does not mention side effects or authorization, but the tool appears to be a read-only graph query, so this level is appropriate.

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 two sentences, front-loaded with the core purpose ('Find what a symbol calls (forward call graph)') and immediately follows with the most important behavioral nuance (noise filtering) plus a pointer to a sibling tool's semantics. No wasted words; each sentence carries meaningful information.

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 has 9 parameters, no output schema, and no annotations, the description is sparse. It explains the overall purpose and one filtering behavior, but omits details about return shape (beyond 'same evidence shape as find_callers', which is not elaborated), default limits, or the meaning of edge_kinds/resolution. A user would need to consult the schema or other tools to fully understand usage. This is insufficient for a tool of this complexity.

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 only 22% (only include and worktree have descriptions in properties). The description adds detail about the include parameter's behavior (default filtering and how to override), which is valuable. However, it does not explain the remaining 7 parameters (id, ref, limit, symbol, edge_kinds, resolution, allow_ambiguous), leaving them underdocumented. The description fails to compensate for the low schema coverage, so the score is low.

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 'Find what a symbol calls (forward call graph)', which is a specific verb+resource combination, and explicitly differentiates from the sibling find_callers by specifying direction ('forward') and noting 'Same evidence shape as find_callers'. This leaves no ambiguity about the tool's core function.

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 implies when to use it (for forward call graph exploration) and contrasts with find_callers via the phrase 'Same evidence shape as find_callers', hinting at a sibling relationship. It also explains a filtering behavior that affects usage (default noise filtering, adjustable via include). However, it does not explicitly state when not to use it or recommend an alternative for other cases, so slightly less than excellent.

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