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

Annotations already declare this as a non-destructive, idempotent write. The description adds useful behavioral context: notes stay on the candidate's history and are never shown to the candidate, and the call fails with decisions_not_allowed unless hiring steps are allowed. It does not fully clarify rating visibility or overwrite behavior, but it meaningfully exceeds the annotation baseline.

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 compact, front-loaded with the action, and uses semicolons efficiently to add notes privacy and failure behavior. No sentence 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?

Output schema exists, so return values need not be described, and annotations cover safety/idempotency. The description adds key context around notes visibility and the decisions_not_allowed failure condition. It is nearly complete, with the main gap being the lack of semantics for job_id and application_id.

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 carry parameter meaning. It explains rating as a 1-5 employer_rating and clarifies notes privacy, but says nothing about the required job_id and application_id parameters. Coverage is therefore partial and leaves two required identifiers undocumented.

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 states a specific verb and resource: setting the member's own 1-5 candidate rating (employer_rating). It also distinguishes the rating action from notes, which are handled separately as history. An agent can identify the tool's purpose 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?

Usage is implied by 'Set the member's own 1-5 rating of the candidate,' and the description gives an eligibility prerequisite via 'unless the member allowed hiring steps.' However, it does not explicitly say when to use this versus sibling tools like set_shortlist, record_interview_outcome, or add_candidate_note.

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