Sign Attribution Consent

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

Annotations already declare the safety profile (readOnly, non-destructive, idempotent, closed-world), and the description adds non-obvious semantics on top: the verification consequence of omission and the key-binding rule that the signature is checked against the key the receipt carries for that party and must be the key that party's DID commits to. That is genuine added context about authorization/key requirements. It does not describe what is returned or how failures surface, which keeps it from a 5, but nothing here contradicts the annotations.

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?

Three tight sentences, front-loaded with the action, then the downstream consequence, then the cryptographic check — each sentence carries information. The only drag is the abstract 'Representation boundary:' opener, which is jargon an agent may not resolve, slightly delaying the concrete verb.

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?

Complexity is moderate (key-bound signing inside an attribution/consent framework) and there is no output schema, so the description should ideally say what comes back (a signed receipt vs. a bare signature) and whether the receipt is mutated. It covers purpose, precondition, consequence and the validation rule well, but the return-value gap is a real omission for a tool with no output schema.

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 100%, so the baseline is 3; the description adds a constraint the schema does not: the supplied private key must be the key the receipt carries for that party and the one the party's DID commits to, which governs key selection. It also ties the 'receipt' parameter back to aps_create_attribution_receipt in the schema. Format/error details for the key parameter are still absent.

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 a specific actor (the cited principal), action (adds their consent signature) and object (an AttributionReceipt), so the tool's function is unambiguous. It also indirectly separates itself from siblings by naming the two consumers (verifyAttributionConsent, checkArtifactCitations) rather than restating its own name. It stops short of an explicit 'use this instead of X' contrast with the sibling signing/receipt tools, which is why it is not a 5.

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?

It gives clear context for calling: without this signature the downstream verifiers reject the receipt, which tells the agent exactly why and when this step is required. There are no explicit exclusions or alternative-routing statements (e.g. relative to aps_create_attribution_receipt or aps_check_projection_consistency), so it matches the 'clear context, no exclusions' band rather than a 5.

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