leave-pto-requests-approvals

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.

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

Annotations provide no positive hints (all false), so the description carries the burden. It discloses the calculation formula, the possibility of half days, and the rounding-down behavior on the report. This goes well beyond the structured fields, though it could mention whether any side effects or permissions apply.

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 two concise sentences with no filler. It front-loads the main action and resource, then gives the formula and rounding behavior efficiently.

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 single-parameter tool with no output schema, the description adequately explains what is computed and what the output looks like. It is missing minor details like error handling for unknown employees, but that is not critical for a simple balance lookup.

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% and already explains that 'employee' is an id or name. The tool description adds no further parameter-level meaning, so it meets the baseline but does not exceed it.

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 ('Show') and a specific resource ('one employee's leave balance'), and it details exactly what the balance consists of. It is clear and distinct from the sibling tools, though it does not explicitly name an alternative tool for comparison.

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 intended use is implied by the description: use this when you need a single employee's leave balance. However, it does not explicitly state when not to use it or point to an alternative such as leave_list.

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

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

The description claims idempotent-like behavior ('Nothing happened if already cancelled') while the annotations set idempotentHint=false, which is a direct contradiction. It otherwise provides useful non-destructive context, but the contradiction forces the lowest score.

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?

Two sentences with no filler: primary behavior first, then sibling differentiation, then edge case. Every sentence earns its place and the structure supports quick comprehension.

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 eligible states, non-destructive outcome, sibling distinction, and the already-cancelled behavior; no output schema exists so return format is not required. It is nearly complete, but the idempotency contradiction leaves an unresolved behavioral question for the agent.

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' and 'reason'. The description adds only 'by id', which does not materially enhance parameter understanding; baseline 3 is appropriate.

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?

Clearly identifies the action ('Cancel'), the resource ('a pending or approved request by id'), and the outcome ('keeping its record with status cancelled'). It also distinguishes itself from the sibling leave_reject by intent, so an agent can select it without opening schemas.

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?

Explicitly states the eligible states (pending or approved), names the alternative leave_reject and the differentiating criterion (voluntary withdrawal), and describes the already-cancelled edge case. This gives clear when-to-use and when-not-to-use guidance.

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

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

The description adds useful behavioral context beyond the non-informative annotations: it returns an EMP-NNNN id, explains how balances are calculated ('approved plus pending leave against allowance + carried-over'), and notes unlimited free-tier usage. This helps an agent predict side effects and follow-up behavior.

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 short and front-loaded with the core action and return value. The phrase 'Give their annual paid-leave allowance...' is slightly awkward and could be read as a user instruction, but the overall structure earns its place.

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 creation tool with a rich schema and no output schema, the description conveys the return idantification format and the balance policy relevant after creation. It is mostly complete, though it could clarify duplicate handling or non-idempotency more explicitly.

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 100%, so the baseline is 3. The description goes slightly further by explaining how annualAllowance and carriedOver interact in balance calculations, which adds meaning beyond the field-level schema descriptions.

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 a specific action ('Add an employee to the leave tracker') and a concrete result ('return their EMP-NNNN id'), making it immediately distinguishable from sibling leave tools. It clearly identifies the resource and the operation.

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?

No guidance is given about when to use this tool versus alternatives such as leave_import or other leave tools. The description explains what the tool does but does not state when it should be preferred or any exclusions.

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

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

Beyond the read-only/idempotent/non-destructive annotations, the description discloses the return value (calendar text), the optional file-write side effect via path, and the watermark-free output. It does not contradict the annotations since the file write is to a specified local output file rather than the tool's core data state.

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 and front-loads the core behavior after a one-word 'Pro.' marker. 'Pro.' and 'watermark-free' are minor extras, but they do not bloat the text or obscure the main call semantics.

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 single-optional-parameter tool with no output schema, the description covers the operation, the input, and the return format. Small ambiguities like what 'local file' means for path resolution remain, but they are not blocking for default invocation.

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 100% and the only parameter (path) already has a schema description. The tool description repeats that path is used to write the file but adds no format, path-resolution, or overwrite details, so it meets the baseline without exceeding it.

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 uses a specific verb ('Export') and resource ('all APPROVED leave as an .ics calendar (RFC5545)'), unambiguously separating it from sibling tools like leave_list or leave_import. The optional file-write behavior is also clearly stated.

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 tool is clearly scoped to exporting approved leave in ICS format, so the intended use is inferable. It does not name alternatives or exclusions, but no sibling tool provides the same calendar-export function, so the context is sufficient.

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

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

With all annotations reading false/non-informative defaults, the description carries the behavioral burden and mostly meets it: it discloses that status defaults to pending, enumerates accepted status values, and — most valuably — states that conflicting rows are reported but not applied, i.e., partial application rather than all-or-nothing semantics. The 'watermark-free, full CRUD' tail adds ambiguity about whether updates/deletes are involved, slightly undercutting the otherwise strong disclosure.

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 sentences, front-loaded with the core purpose, then header format, then status and conflict behavior — good progressive structure. The final 'watermark-free, full CRUD' clause is the only non-operational content and reads like plan marketing rather than guidance.

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 input side is well covered for a one-parameter tool with no output schema: format, header, defaults, and conflict behavior are all present. The gap is the response — conflicting rows are 'reported' but the shape of that report and of a successful import is never described, and an agent cannot predict the return value. The Pro-license requirement is also only hinted at.

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?

The schema already documents the sole csv parameter at 100% coverage, but the description adds meaning the schema lacks: allowed status values (approved/rejected), the omission default (pending), and per-row conflict checking. It does not specify date or halfDay column formats, which remain undocumented in both places.

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?

Leads with a specific verb and resource — 'Bulk-create leave requests from a CSV/TSV' — which immediately distinguishes it from single-record siblings like leave_request, leave_approve, and leave_cancel. The header specification and status rules further pin down the operation. The closing 'watermark-free, full CRUD' phrase is slightly muddled but does not obscure the core purpose.

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 'Bulk-create ... from a CSV/TSV' phrasing establishes a clear usage context: use this when many leave requests need to be created at once from a file, in contrast to the individual flow of leave_request. However, it never names an alternative or states when not to use the tool, and the 'Pro' prerequisite is a tag rather than an explained gating condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful default behavior (no filters means all requests) but does not disclose pagination, sorting, or response format for a list operation.

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?

Two short sentences contain the core behavior and a default-case hint with no filler. The wording is compact, though the employee/request ambiguity could be resolved without adding length.

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 tool has no output schema and presents a dual-purpose behavior, yet the description doesn't specify the trigger for listing employees versus listing requests. It also omits practical list-operation details like pagination, limits, or response structure, making it incomplete for an agent to invoke confidently.

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?

Input schema already describes both parameters with 100% coverage, providing the baseline. The description adds value by clarifying that the filters are optional, can be combined ('and/or'), and that omitting them returns all requests.

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 ('List') and resources ('all employees', 'all leave requests') and mentions filters, so it is not a pure tautology. However, it never explains what determines whether employees or requests are returned; the schema has no parameter for selecting the resource type. This ambiguity keeps it from being fully clear.

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 implies this is the go-to tool for listing leave data and gives a default-behavior hint ('Omit the filter to list requests'). It does not explicitly say when to prefer it over siblings such as leave_balance or leave_export_ics, nor when not to use it.

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

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

The description adds useful behavioral details beyond annotations: inclusive date handling, each employee appearing once per day, and pending requests counting as a plan. However, annotations mark readOnlyHint as false, and the description does not clarify whether the tool has any side effects or what the return structure looks like, leaving some behavioral ambiguity.

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 and front-loaded with the core purpose. Each sentence adds value: main behavior, edge-case semantics, use cases, and free-tier constraint. No filler or redundancy.

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 tool with no output schema, the description is nearly complete: it explains scope, date format, per-day deduplication, pending-request handling, and suggested use cases. It only slightly lacks explicit guidance on when not to use it or which sibling to prefer.

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?

The schema already describes both parameters with format and inclusivity, achieving 100% schema description coverage. The description restates 'start and end are inclusive YYYY-MM-DD,' which reinforces the schema but adds little new parameter-specific meaning.

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 clearly identifies the tool as a date-range absence query ('Who is out in a date range') with inclusive start/end dates. It is distinguishable from siblings like leave_request or leave_approve, though it does not explicitly differentiate itself from leave_list.

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 explicitly states when to use the tool: 'Use for coverage, calendars and absence summaries.' It provides clear use-case context but does not mention exclusions or alternatives, such as when leave_list or leave_balance would be more appropriate.

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

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

Annotations provide only basic flags, so the description adds real value by defining the status transition (pending/approved to rejected) and the reopen path. It does not cover permissions, side effects, or error behavior, but it gives meaningful behavioral context beyond the schema and annotations.

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 contain no filler and front-load the core action. The final parenthetical is slightly awkward but not wasteful.

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 mutation tool, the description covers the main status behavior and routes to relevant siblings. The lack of an output schema and return-value note is a minor gap, but not critical at this complexity.

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?

The schema already documents both parameters with 100% coverage, so the description need not repeat them. It adds only 'by id' and a hint that a reason is involved in cancellation, which is marginal beyond the schema.

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 action and resource ('Reject or cancel a leave request by id') and adds state-transition detail that distinguishes it from leave_approve and leave_cancel. The word 'cancel' slightly overlaps with the sibling name, but the state wording resolves most ambiguity.

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 explicitly says a rejected request can be reopened with leave_approve and that leave_cancel should be used for voluntary withdrawal. The conditions are clear, though the parenthetical '(via reject with reason)' leaves some uncertainty about whether leave_cancel is an alias or a separate call.

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

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

With annotations offering no meaningful behavioral guidance, the description carries the burden and adds useful details: return format, inclusive date semantics, halfDay effect, overlap refusal, and free-tier limits. It does not contradict the annotations, and no annotation contradiction is present.

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?

Four short sentences, each with a distinct job: purpose/return, parameter semantics, validation behavior, and quota. Front-loaded with the core action and free of filler.

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 moderate-complexity tool with 6 parameters and no output schema, the description covers the action, return id, date/type/halfDay semantics, overlap behavior, and quota context. It could add explicit failure/error behavior, but what is present is sufficient for correct invocation.

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 100%, so the baseline is 3. The description mostly restates what the schema already provides (type enum, inclusive dates, halfDay behavior), with the only notable addition being the LV-NNNN return id, which is not parameter-specific.

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 specific verb-resource pair ('Create a leave or PTO request') and states the return value (LV-NNNN id), making the tool's function unambiguous. It also contrasts naturally with siblings like leave_approve, leave_cancel, and leave_reject.

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 makes it clear this is for creating leave requests, but it does not explicitly state when to prefer this over sibling tools or mention exclusions such as checking balances first. Usage context is implied rather than explicit.

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

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

Annotations already indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.

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 two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential 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?

For a single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent to call it correctly.

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?

The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in the schema.

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 uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.

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 provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the workflow.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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?

Two dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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?

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.

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?

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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 explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.

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