writ_grant

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

With no annotations, the description carries the full burden and does well: it discloses single-use consumption semantics ('the next writ_check consumes it and returns ALLOW'), tenant scoping, and the required WRIT_SPONSOR_TOKEN. It does not explain grant expiry behavior (ttl_seconds) or failure/error modes, which leaves a small gap.

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 short sentences, front-loaded with the sponsorship constraint and purpose, then the trigger condition, then the consumption behavior. Every sentence adds distinct information with no repetition of the schema.

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 output schema exists so return values are covered, and the workflow context is strong, but for a 6-parameter, 0%-coverage security-sensitive tool the parameter and expiry semantics are under-specified. Adequate for routing, thin for correct invocation.

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 0% and there are 6 parameters, so the description must compensate. It only vaguely gestures at 'verb', 'target', 'purpose' via 'a specific action', plus sponsor and token, while ttl_seconds, agent_id, and sponsor_id are never explained in a way that adds meaning beyond the bare property names.

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 specific verb and resource: 'Mint a one-time grant approving a specific action', with a hard scope qualifier ('SPONSOR ONLY'). It implies its role relative to writ_check, but does not explicitly contrast itself with the other siblings (writ_revoke, writ_verify_token, etc.).

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 an explicit trigger condition: 'Use this when writ_check returned STEP_UP and the human sponsor approves.' This names the prerequisite tool and the human-approval gate, so the agent knows exactly when this tool is applicable rather than inferring it.

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