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

Beyond destructiveHint=true and idempotentHint=false, the description discloses the two things an agent most needs: the secret is returned once and must be stored immediately, and existing triggers emit two v1= signatures (new first) until previous.expires_at. That is real consequence-level disclosure the annotations cannot carry.

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 dense clauses, no filler, and the irreversible part (shown once) comes first. The middle clause about previous.expires_at and dual signatures is telegraphic enough to require a second read, which costs it a point.

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 destructive, non-idempotent mutation with no output schema, the description covers return-value handling, backward compatibility during grace, and the endpoint. Missing only authorization/rate-limit notes and what happens to the old secret after the grace window expires.

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% — job_id and management_token are documented in the schema, but grace_sec has no schema description at all. The description compensates by explaining grace_sec as the window controlling previous.expires_at and giving its 24-hour default, which is meaningfully more than the schema offers.

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 front-loads the outcome — a new hmac_secret — which makes the rotation effect concrete, and the title/name supply the verb+resource. It does not, however, distinguish this from the sibling rotate_token, which rotates a different credential; an agent must infer the difference from the secret name alone.

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?

There is no explicit statement of when to call this versus rotate_token, nor any prerequisite guidance. The grace-window detail implies an operational context (rolling deployment) but never says when rotation is warranted or discouraged.

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