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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description extends this materially: it discloses that list fields REPLACE wholly (the destructive surface), the optimistic-concurrency version check, that a stale read saves nothing, and the `previous` return value so the agent can report removals. The interview_mode charge implications add further context 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?

The critical constraints (draft-only, list-replacement, version check) are front-loaded before the field-level detail. It is dense but long; a couple of the semantic glosses (interview_mode cost model) could be tightened, but nearly every sentence carries operational weight for a destructive mutation.

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 needn't be described, and the tool is well covered on the risky dimensions: draft-only guard, replace semantics, concurrency, and delete-and-report behavior. The main gap is the untouched scalar fields (cv_pass_threshold, interview_questions) that a caller might routinely pass.

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 compensate. It documents nested shapes for knockout_questions and scoring_criteria, the interview_mode enum semantics, instant_start_enabled conditions, and version's role. However title, description, cv_pass_threshold, and interview_questions receive no guidance, leaving several of the 10 params underspecified.

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+resource ('Edit a DRAFT job') and immediately names its failure mode (published job -> job_not_draft), which distinguishes it from create_draft_job and the add_* question siblings. An agent can tell exactly what this does without opening the 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?

Explicit when-to-use: read with get_job right before, pass its version, rebuild lists from current state. Explicit alternatives: 'To ADD one question, use add_knockout_question or add_interview_question instead.' The retry path on job_changed is spelled out. Nothing is left to inference.

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