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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds meaningful behavioral context by requiring 'explicit approval metadata' and a 'matching idempotency key,' which are not captured in the annotations. It does not contradict the annotations and supplements them with the safety/confirmation requirements.

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 a single sentence and front-loads the key action ('Bind an already-previewed job-posting archive'). It is concise and contains no filler, but the dense terminology ('approval metadata', 'matching idempotency key') slightly reduces immediate readability. Overall, it is appropriately sized and structured for its content.

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?

Given the complexity of the tool (nested 'binding' object, 4 parameters, no output schema, and 0% schema-description coverage), the one-sentence description is inadequate. It does not explain how the binding object is structured, how the idempotency key should match, or what the result of binding looks like. An agent would need to infer most details from the schema alone, which lacks descriptions.

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 description coverage is 0%, so the description must compensate for the lack of parameter documentation. It only refers vaguely to 'approval metadata and matching idempotency key' without explaining the individual parameters (preview_hash, approved_action_key, approved_input_hash, resource_version_precondition) or the nested binding object. This is insufficient for an agent to correctly construct the parameters.

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 uses a specific verb ('bind') and resource ('job-posting archive') and adds the qualifier 'already-previewed,' which distinguishes it from the sibling preview tool. The title 'Confirm and archive a job posting' further clarifies the action, though the use of 'bind' and 'approval metadata' is somewhat technical. It clearly identifies this as the post-preview confirmation/commit step.

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?

The phrase 'already-previewed' implies the tool must follow yardstick_job_postings_archive_preview, but it does not explicitly name the sibling or state when not to use this tool. There is no mention of alternatives or exclusions, so the guidance is implied rather than explicit. This meets the threshold for 'implied usage' but falls short of clear when/when-not guidance.

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