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

Goes well beyond the annotations: it spells out exactly what is destroyed (job document, public listing), what survives (audit snapshot), that pending_review jobs are included, and that no money is charged or refunded. That corroborates destructiveHint and idempotentHint while adding the operational detail the hints 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?

Front-loaded with what the tool does, then consequences, then safety gate, then parameter source – a sensible order with no filler sentences. Density is high but every clause conveys a distinct fact.

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, idempotent, no-output-schema tool this covers nearly everything an agent needs before calling. The only minor omission is what a successful call returns or looks like (confirmation payload), which would help the agent verify the removal.

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 the load and it does: jobId's provenance (from list_my_jobs), the fact that all three action enum values mean the same removal, and the confirm=true requirement are all documented. No parameter is left 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?

"Removes a job posted by the signed-in user" gives a specific verb (remove), resource (job), and ownership scope. It also explicitly collapses the three action synonyms (close/withdraw/delete), which is exactly what an agent needs to disambiguate against siblings like cancel_booking or close_meeting_room.

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?

It states the gating condition ("Does nothing unless confirm=true") and points the agent at list_my_jobs for the jobId, so the agent knows both the prerequisite and where to get input. It doesn't name an alternative tool for cases where the user might actually want to cancel a booking or pause a job, but no true sibling overlap exists here.

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