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

The description explicitly claims 'Idempotent: returns success even when the user was not subscribed or is already unsubscribed,' but the annotations declare idempotentHint=false. This is a direct contradiction of a declared behavioral trait, which is the most consequential kind of error for an agent deciding whether retries are safe.

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?

Roughly four sentences, front-loaded with the action, then clearly delimited Input/Output sections. The Input paragraph carries real information (accepted ID formats and their origin) rather than padding, and nothing is wasted.

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?

An output schema exists, so return values need not be explained, and the description still adds the ID-sourcing guidance and the idempotency/error behavior an agent needs. The only gap is the missing contrast with job_alert_unsubscribe_all, and the idempotency claim is contradicted rather than merely incomplete.

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 already 100%, so the baseline is 3; the description goes slightly beyond by naming the tools that produce the composite 'seo_id--job_search_id' value (jobs_search / jobs_details) and by restating requiredness, which helps an agent source the value correctly.

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 (unsubscribes), resource (job alerts), and scope (for a specific job search, by the authenticated user), which naturally distinguishes it from job_alert_unsubscribe_all and job_alert_subscribe. An agent can pick this tool over its siblings 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?

Usage is implied by the name and the 'specific job search' scoping, and the description helpfully says where the accepted ID format comes from (jobs_search / jobs_details). However, it never states when to prefer this over job_alert_unsubscribe_all, nor any prerequisites (e.g., auth/scope requirements) or exclusions.

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