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

With no annotations provided, the description carries the transparency burden. It discloses the signing process, security boundary (no private key transmission), and the social/legal notion of witnesses. It doesn't detail return values or error behavior, but it gives a strong sense of what happens and why.

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?

The description is front-loaded with a clear purpose, then a compact workflow, a security rule, and an illustrative note on multi-party attestation. Every sentence earns its place; it's dense but not bloated.

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 tool with no annotations and no output schema, the description is remarkably complete. It integrates with the broader flow, explains the cryptographic steps, warns about private keys, and even provides a rationale for multi-party attestation. The only minor gap is the lack of return-value details, but that's not required when no output schema is present.

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?

The schema only describes attestation as 'the dict from signing.sign_seal' and gives no description for content_hash. The description compensates by explaining that content_hash is the returned hash from a previous unsigned action and enumerates the attestation fields ({alg, over, content_hash, pubkey, sig}). However, 'submit only the attestation' could be misleading given the schema requires a top-level content_hash in addition to the attestation object.

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 opens with a clear verb and resource: 'Bind your identity to a record you already hold.' It distinguishes itself from siblings by referencing the 'sovereign flow' and specific preceding tools (badges_issue, study_export, group_contribute), making its role unmistakable.

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 provides explicit step-by-step usage: perform an unsigned action, get the content_hash, sign it locally, and submit the attestation. It also advises 'never send a private key' and notes multi-party attestation. Though it doesn't name alternatives to explicitly say 'use this instead of X', the reference to 'phase 2' and the workflow effectively imply context.

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