approve_interview

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 handles it well: 'Live mutation' signals side effects, the permission list states authorization preconditions, and 'expect the returned state/audit fields to vary by Headquarters build' flags unstable return values. It stops short of describing what state an approval transitions the interview into or whether the action is reversible, but this is strong behavioral disclosure for an annotation-free tool.

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?

Three front-loaded sentences, each earning its place: core action first, then permission and confirmation-guard requirements, then the live-mutation warning with a return-value caveat. No filler, no restatement of the tool name or schema.

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?

Covers purpose, authorization, the confirmation guard, side-effect nature, a read-first precondition, and a return-value caveat — strong for a 4-parameter mutation with no annotations and no output schema. The remaining gaps are the unexplained comment/profile parameters and the lack of an explicit nod to the reject_interview or hq_approve_interview alternatives.

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 only 25% — confirm_interview_id is the only documented parameter ('Must exactly match interview_id') — and the description's 'exact interview ID confirmation' largely restates that same schema constraint rather than adding new meaning. comment and profile receive no explanation in either the schema or the description, leaving the 75% coverage gap uncompensated.

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 the action and actor plainly — 'Approve an interview as supervisor' — with a specific verb and resource. The supervisor role plus the fieldwork_write/admin_write permission hint distinguishes this from the HQ-level approval siblings like hq_approve_interview, though no sibling is named explicitly.

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?

Provides concrete usage context: permission prerequisites ('Requires fieldwork_write or admin_write permission'), a safety precondition ('read current status first'), and a live-mutation warning. It never names the alternative tools or states when-not-to-use, so routing away from reject_interview or the hq_* variants is left to implication rather than explicit exclusion.

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