trace_data_flow

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

The description explicitly states 'Read-only' and notes limitations like inability to follow async flows. It describes the output (data flow map) but could be more detailed about performance or side effects; however, with no annotations, it carries the burden well.

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 clear summary, then provides details, limitations, and alternatives. Every sentence adds value 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 complexity (5 parameters, no annotations) and the presence of an output schema, the description covers all necessary aspects: inputs, output, limitations, and usage context. It is sufficiently complete for an AI agent to decide when and how to use 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?

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema by explaining the purpose of type_name and to_symbol in tracing, and notes auto-detection for project_root. It also indirectly guides parameter choices via usage context.

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 what the tool does: 'Trace how data of a given type flows to a target function.' It uses a specific verb and resource, and explicitly distinguishes from siblings like find_call_path and the find_* family.

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?

It provides explicit guidance on when to use (understand data flow in synchronous stacks) and when not to (async flows are unsupported). It also names alternatives: 'For exact call-graph queries use the find_* family; verify specific paths with find_call_path.'

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