Update candidate intelligence status

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

With no annotations present, the description carries the full disclosure burden and does meaningful work: it reveals that transitions are strict, that promoted and rejected are idempotent terminal states, and that promotion records approval/evidence without writing to a knowledge base. It does not cover error behavior or reversibility, but the key side effects are exposed.

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 three tight sentences: the action is front-loaded, transitions are compactly diagrammed with arrows, and the idempotency/KB side-effect are the only extra details. No filler or repeated schema information.

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?

The state machine is the core complexity of this tool and it is fully specified, from allowed transitions to terminal state idempotency. The existence of an output schema covers return-value documentation. Slight gaps remain around whether same-status updates are allowed for non-terminal states and how user_note behaves, but the description is strong enough for correct calls in most scenarios.

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 undocumented parameters. It clarifies the status enum by encoding transition rules and links promotion_reason/validation_evidence to the approval-and-evidence note. However, user_note is never mentioned, and the mapping from 'user approval' to specific parameters is implicit rather than explicit.

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 opens with a precise action: 'Advance a candidate through discovered, shortlisted, validated, promoted, or rejected,' naming both the resource (candidate) and the state-machine operation. It also supplies the full status vocabulary, which distinguishes it from sibling tools like record_candidate_intelligence that target candidate facts rather than lifecycle progress.

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 description states when to use the tool: whenever a candidate must move along the strict lifecycle. It spells out the allowed transitions and terminal states, so an agent knows valid calls are constrained by the current status. It does not explicitly name alternative tools for non-status updates, but the lifecycle rules make the tool's scope clear.

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