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

Annotations only flag the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds the crucial behavioral fact an agent cannot infer: this is a two-phase write — it only prepares an intent, and nothing is committed until an external signer plus geode_submit_intent complete the flow. No contradiction with the non-destructive annotation.

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?

Two sentences, no filler. The core action is front-loaded, and the transaction-follow-through caveat follows immediately where an agent will read it before invoking.

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?

With no output schema, the description should explain the return and edge cases; it does imply the return is an unsigned intent and names the follow-on tools. It does not cover failure modes (claim not found, not your claim) or whether hiding is reversible/retains endorsements, but the essential call path is complete.

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 67% (signer and claim_id documented; set_to_show bare). The description reinforces the signer role and implies the boolean via 'show or hide', but adds no new semantics beyond the schema — e.g. it never says the claim must be one you own. Baseline 3 is appropriate when only a third of the params lack description.

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 toggle verb ('show or hide') applied to a specific resource ('one of your Life and Work claims on your resume'). This is clearly separable from the sibling make_claim_* tools (which create claims) and endorse_claim (which signs support), so an agent can route correctly without opening any schema.

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 concrete pipeline context: it prepares an unsigned intent for `signer`, and 'nothing happens until you sign it with geode-local-signer and submit it with geode_submit_intent'. This names the required follow-on tools. It stops short of stating when to prefer this over related lifecycle operations (e.g. after making a claim), but the action constraints are explicit.

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