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

Beyond annotations, the description discloses key behavioral traits: 'Nothing is deleted: the edge is retained, marked with who removed it and when, and the removal is appended to a ledger that survives everything after it.' It also notes behavior with archived tickets and stable rejection codes. This adds significant value beyond the annotations, which only state non-read-only, non-idempotent, non-destructive.

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: one leading sentence states the action, then a few sentences cover behavior, exclusions, archive handling, and rejection codes. Every sentence adds value with no repetition or fluff, so it earns a 5.

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, the description is remarkably complete. It covers the action, side effects (no deletion, ledger record), edge cases (archived tickets), error semantics (stable codes), and semantic distinction from marking work complete. The output schema is present, so return values needn't be described. This leaves no significant ambiguity.

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?

The schema has no descriptions, but the description clarifies the roles: 'ticket_id' is the owned (waiting) ticket and 'dependency_id' is the prerequisite. It also implies that the dependency is an 'edge' that can be removed. This compensates for the 0% schema coverage, though not as explicitly as it could. I give 4.

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 action: 'Stop an owned ticket from waiting on a prerequisite.' It uses a specific verb and resource, distinguishes from sibling tools (ticket_dependency_add, ticket_dependency_list) by describing the removal action, and clarifies the effect ('gate-opening action'). This is unambiguous and informative.

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 gives clear context for when to use this tool: to remove a dependency edge that makes a ticket wait. It explicitly contrasts with a different action: 'This is not a way to say the prerequisite work is finished — that remains a separate statement about that ticket.' While it doesn't name specific alternative tools, the exclusion clarifies boundaries, so I give 4.

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