project_change

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

With no annotations, the description carries the full behavioral burden. It discloses receipt storage, transitive consumer-chain computation, max_distance truncation with lazy loading, the distinction between import dependency and runtime data flow, and the uncovered non-Python case. It does not mention failure modes or permission requirements, but the disclosed semantics are substantial.

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?

Four dense sentences with no filler; the primary purpose is front-loaded and each sentence adds distinct information about behavior, limits, semantics, and edge cases. This is appropriately concise for the tool's complexity.

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 covers the core behavior, truncation and lazy loading, the meaning of import edges, and the non-Python limitation—strong coverage given no annotations and no output schema. It still leaves the exact response envelope and the verification array semantics unspecified, so a perfect score is not warranted.

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 only 40%, so the description must compensate. It does clarify max_distance (return truncation) and implies verification via 'verified commit,' but it does not explain what verification items should contain or how project_root is used. The schema already describes base_commit and semantic_summary, so the description adds only partial parameter value.

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 names specific actions: storing a compact change receipt and computing the complete transitive chain of statically proven Python import consumers. This clearly distinguishes the tool from generic project or knowledge tools and gives an agent an unambiguous sense of what it does.

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 precondition 'After a verified commit' gives clear context for when the tool applies, and the max_distance/lazy-loading explanation clarifies how results are scoped. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full alternative routing.

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