Approve leave

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

The annotations already mark this as a non-read-only, non-idempotent action. The description adds state-transition behavior beyond the annotations: it approves pending requests, re-opens rejected ones, and treats already-approved requests as having 'nothing to approve'. No contradiction exists.

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 short sentences, each carrying distinct information: primary action, secondary use, and an edge-case warning. No filler or repetition.

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?

For a simple two-parameter state-change action with no output schema, the description is complete: the agent knows what to invoke, which statuses qualify, and that already-approved requests should not be processed. No additional context is essential.

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 100%, so the schema already documents 'request' as the request id and 'comment' as the approval note. The description only echoes 'by id' and adds no new parameter semantics.

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 names the action 'Approve' and the specific resource 'a pending leave request by id', and spells out the secondary use case 're-open a rejected one'. It also warns that an already-approved request has nothing to approve, which helps differentiate it from siblings like leave_reject and leave_cancel.

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?

It states clear conditions: use for pending requests, use to re-open rejected ones, and do not use on already-approved requests. It does not explicitly name sibling alternatives like leave_reject, but the when/when-not guidance is otherwise explicit.

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