Mint Capability Challenge Receipt

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which matches a deterministic signature over a fixed hash, so there is no contradiction. The description does add real context beyond annotations: the output is a signed permit/deny and it echoes the M2 delegation_chain_root so the sink can confirm chain agreement. However, it says nothing about the handling of the required gateway_private_key (sensitivity, whether the key is persisted, error behavior on signature failure), which an agent calling a signing tool needs to know.

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?

Roughly four sentences, front-loaded, and not bloated, but the leading 'v0.1 capability-token gateway receipt (M3)' is opaque rather than informative, and the trailing 'Search keywords' list is keyword-stuffing that consumes space without helping an agent decide or call correctly. No sentence is egregiously long, but the structure prioritizes version tags over the actual precondition and output.

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?

For a six-parameter, five-required cryptographic tool with no output schema, the description should explain what the returned receipt looks like and when the tool is valid to call. It gestures at the receipt contents (signed decision, echoed chain root) but omits the call ordering relative to sibling capability tools, the meaning of deny_reason, and any key-handling caveats. It is not sufficient to invoke the tool reliably.

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 only 33%: request (partially) and policy_digest are annotated, while decision, deny_reason, gateway_public_key, and gateway_private_key carry no description in either the schema or the tool description. The description mentions challenge_hash and delegation_chain_root, which are not top-level parameters at all, so it does not compensate for the gap. With five required parameters, this leaves the caller guessing about half the inputs.

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 does name a concrete action (gateway signs a permit/deny over the sink's challenge_hash) and a concrete artifact (capability-token gateway receipt), so the mechanics are identifiable. But it is dense with undefined domain jargon ('M3', 'sink', 'delegation_chain_root') and never distinguishes itself from the closely named siblings aps_capability_issue_challenge, aps_capability_evaluate_authority, or aps_capability_sign_effect. An agent unfamiliar with the ontology can tell it produces a signed receipt but not confidently place it in the pipeline.

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?

There is no when-to-use guidance at all. The description never says whether this is called after aps_capability_evaluate_authority, before aps_capability_sign_effect, or what precondition (an M2 delegation chain, an existing challenge) must hold first. Only a 'Search keywords' line is offered, which aids retrieval, not invocation.

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