Grant Drop

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

With no annotations, the description carries the load, and it does disclose a genuine side effect: the removed entry plus the reason are appended to grants_dropped.jsonl. It does not say whether the grant is deleted outright or merely marked dropped, whether it is reversible, or what authorization is needed for a destructive operation.

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?

Two compact sentences with the action and the audit-log behavior front-loaded; nothing is padded. The parenthetical is slightly informal but it earns its place by giving the use case.

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?

An output schema exists, so return values need not be described, and the audit-trail note is a useful addition. But for a destructive, annotation-free mutation, the definition omits reversibility, effect on existing routes, and the meaning/format of the id parameter.

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 0%, so the description must compensate. It explains that "why" is required and that the reason is persisted, but leaves "id" entirely undefined — the agent is not told whether it is a grant id, a route id, or where to obtain it (presumably grant_list).

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?

States a concrete verb+resource ("Take a grant or route out") with the parenthetical clarifying the two grounds for doing so. It is distinguishable from grant_add/grant_list by implication, but it never names those siblings explicitly to confirm the inverse relationship.

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?

Gives real when-to-use context — the grantee withdrew or the grant was wrong — which tells the agent what situation this call is for. It stops short of stating when NOT to use it or pointing at grant_list/grant_check as the alternatives, so the routing guidance is implicit.

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