trace_prop_flow

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal key behaviors: direction semantics and use of the import graph. However, it does not describe output format, behavior on cycles, or what 'both' direction yields, leaving significant gaps for an agent anticipating return values.

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 long and immediately front-loads the core purpose. It avoids redundancy and every phrase adds value, making it highly efficient.

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 tool has 7 parameters and no output schema, so the description should ideally explain what the trace results look like. It gives a hint about direction outcomes but omits return structure (e.g., list of files/components, match info). Parameter details are well-covered by the schema, but the absence of output description reduces completeness for this moderately complex tool.

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 100%, so the schema already documents every parameter. The description adds marginal value by explaining direction semantics (already in schema) and the import graph mention, but it does not introduce new parameter-level meaning beyond the schema.

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's function: tracing a prop through the component hierarchy. It distinguishes itself from sibling tools like trace_state_updates by focusing on props rather than state, and it specifies the two direction modes (up/down) which clarifies its scope.

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 each direction ('up' finds origin, 'down' finds propagation) and mentions cross-file tracing via the import graph. However, it does not explicitly compare against alternatives like find_component_usages or state when this tool is not appropriate, so context is clear but exclusions are absent.

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