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

Annotations already flag destructiveHint/idempotentHint, and the description adds genuinely non-obvious behavior: the operation is free, it does not grant real-person likeness consent, the returned operation is an immutable historical receipt, and only current.declaration in active state supplies rightsProof. The no-auto-retry reconciliation rule is exactly the kind of guidance annotations cannot express.

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-loads the core action and precondition, then layers constraints and non-uses in a sensible order; nearly every clause carries distinct information. It is dense and slightly sprawling in the middle (free/does-not-do list), which keeps it off a 5.

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 5-parameter nested mutation with no output schema, the description covers the full workflow (get → confirm → save), version conflict handling via expectedVersion, the immutability and state semantics of the returned object, and the retry/reconciliation stance. Nothing an agent needs to call this safely is missing.

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?

With 0% schema description coverage, the description carries the load and does: it explains ownerConfirmed must be true, expectedVersion comes from soclo_rights_declaration_get with 0 as the absent case, clientRequestId must be stable and reused on reconciliation, and declaration is the owner's own words. It also resolves the nested scope object: new saves need no scope selection, and a legacy scope is only sent back unchanged to reconcile its original request.

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 — record the owner's own words as their creative rights declaration — and implicitly distinguishes itself from soclo_rights_declaration_get (source of expectedVersion) and soclo_rights_declaration_withdraw in the sibling set. The scope of effect (covers lawful current and future account uploads) is spelled out rather than left to inference.

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?

Gives explicit preconditions (only after explicit confirmation with ownerConfirmed: true; expectedVersion from soclo_rights_declaration_get, 0 if absent; stable clientRequestId), explicit prohibitions (never invent, paraphrase or auto-confirm), explicit non-uses (does not approve a price, review an identifiable person, upload a photo, create an actor or generate anything), and a recovery rule (keep same ID and words; do not automatically retry).

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