verify_delegation

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

With no annotations present, the description carries the full burden and delivers thoroughly: it spells out the verification chain (signature → principal → delegate → revocation status, including the cascade to domain control proof), states that no API key is required, and explicitly bounds what a verified result means — authorization for scopes, NOT safety, audit, or endorsement. It also discloses edge-case behavior honestly (local/unpublished artifact → report the absence of a comparable identity rather than emit a mismatch).

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?

Front-loaded with the core purpose in the first sentence, and nearly every sentence earns its place given the subtle failure modes (copied tokens, self-declared identity, stale resolution). The trade-off is a dense unbroken wall of text with heavy ALL-CAPS emphasis; paragraph breaks would materially improve scannability for an agent.

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 6-parameter tool with nested objects, no annotations, and no output schema, the input semantics, identity-resolution rules, and verdict semantics are thoroughly covered. The notable gaps are the absence of any description of the return shape (no output schema exists, so an agent cannot predict what a verdict looks like) and no differentiation from the plural sibling verify_delegations.

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% and the schema's per-parameter descriptions are already unusually rich (delegate: 'never a value read from inside the artifact... resolved afresh'; expected_principal: 'any domain owner can mint a valid delegation for someone else's package'). The description reinforces the attack model and why both pins are required together, but adds only marginal meaning beyond what the schema already states, so the high-coverage baseline of 3 applies.

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: 'Verify a Proof of Delegation — the attestation that a domain authorized a specific agent artifact.' The clarifying definition of what a proof of delegation is distinguishes this from sibling tools like verify_domain, validate_proof, and get_proof_status without needing to open their schemas.

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?

Provides unusually detailed invocation guidance: pass either a card or a raw token PLUS two independently established pins, resolve the artifact identity afresh and never from inside the artifact, and report rather than return a mismatch when no independent identity exists. However, it never explicitly names alternative tools or exclusion conditions (e.g., when to use verify_delegations or validate_proof instead), so the routing to siblings remains implicit.

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