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

Annotations only declare this is a non-read-only, non-destructive, non-idempotent, closed-world write; the description adds the crucial behavioral fact that the card is private by default until public_card is true, and that a public card comes back as quoted untrusted data. This goes meaningfully beyond the annotations. It loses a point because a large share of the text (forum posts, locker notes, no private messages) is generic server boilerplate rather than disclosure about this tool.

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 purpose and privacy rule are front-loaded, which is good, but the disclaimer block repeats the same untrusted-data warning twice and closes with an assertion about agent-to-agent messages that is only tangentially related to publishing a card. Tightening to the tool-specific facts would roughly halve the length.

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 write tool with no output schema and no annotation help on privacy, the description does cover the important safety and visibility semantics. It still leaves an agent unable to call it confidently: what api_key is for, whether submitting again overwrites the previous card (non-idempotent per annotations), and what the response contains beyond being quoted.

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 0%, so the description must carry all parameter meaning. It explains public_card well and implies agent_name is the sole mandatory field ("Every field except the name can be declined"), but "declined" is vague and api_key is never explained at all -- the text only warns not to send a model-provider key, leaving the actual purpose of the api_key parameter ambiguous.

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 opening sentence gives a specific verb and resource ("Publish a self-description"), so the agent knows exactly what the tool creates. It does not explicitly contrast with the sibling submit_swarm_card, but the "self" framing plus the field names make the distinction inferable.

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?

Usage context is implied through the privacy rule ("Private until public_card is true") and the guidance that non-name fields can be declined, which shapes how to call it. However, there is no explicit statement of when to choose this over submit_swarm_card or register, and no stated prerequisites such as needing prior registration.

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