milestone-schedule

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

With annotations carrying only generic false hints, the description supplies meaningful behavioral detail: the operation returns counts, refuses due dates before the reference document's date, and starts the deliverable as 'planned'. It does not disclose every side effect, but it covers the main behavioral traits an agent needs.

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 earning its place: the first states the action and return value, the second clarifies a critical monetary unit, and the third warns about a validation rule and initial status. 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?

For a 7-parameter creation tool with no output schema, the description gives the key context: return values, unit semantics, a validation constraint, and initial state. The schema covers the remaining parameter details, so nothing critical is missing for invoking 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?

Schema description coverage is 86%, so the schema already documents nearly all parameters well. The description reinforces value_minor semantics ('NET of VAT in whole MINOR units') and the due-date constraint, but adds little beyond the schema; it earns the baseline for high schema coverage.

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 verb ('Add'), a specific resource ('one dated deliverable'), and a concrete outcome ('return its D number and the new counts'). It is clearly distinct from the sibling tools, which delete, get, list, or change deliverable status.

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 establishes clear usage context: it is for creating one dated deliverable, while siblings handle deletion, status, and schedule-level operations. It does not explicitly state exclusions or alternatives, but the action and resource are unambiguous among the sibling set.

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 annotations already tell us this is destructive (destructiveHint: true) and not read-only, so the basic safety profile is covered. The description adds a specific behavioral consequence: the D number on a schedule is never reissued, which informs the user of a lasting side effect beyond the deletion itself. It also implies refusal behavior for non-planned states, but doesn't specify error codes or whether the operation is atomic. That's a modest but valuable addition beyond the 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?

The description is a single, compact paragraph: two clear sentences plus a short standalone sentence about the D number. It front-loads the core action and the critical restriction, and every sentence contributes to the user's decision-making. There is no fluff.

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?

Given the tool has only 2 parameters, both fully documented in the schema, no output schema (so no return values to explain), and annotations already carry the destructive hint, the description covers the essential usage context: what is deleteable, what is refused, what the alternative is, and a key invariant. Nothing critical is missing for an agent to decide to call it and pass the correct parameters.

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 fully documents both parameters with examples and clarifiers (e.g., schedule: 'The schedule id... or its title'), so description doesn't add much. The description does add the nuance that the deliverable must be 'planned' and that the D number is never reissued, which indirectly clarifies the semantic scope of the deliverable parameter. However, since schema coverage is 100%, the baseline of 3 is appropriate, and the description provides marginal extra context.

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 states the action (delete) and the resource (a planned deliverable), and immediately distinguishes it from deleting a schedule by using the specific resource name. It also clarifies the scope: only deliverable still planned with no history are deleteable, which carries precise semantic intent.

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 NOT to use it: one started, delivered, or accepted is refused, and names the alternative ('add a corrected deliverable instead'). This is an explicit when-not and alternative guidance, which is exactly what the dimension asks for.

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 a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable behavioral details: it validates the sequence order, refuses out-of-order moves, rejects dates before the reference document, and states that the date drives lateness calculations. This goes beyond the annotations and helps the agent anticipate validation failures.

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 sentences with no filler. The core action is front-loaded, constraints are stated directly, and the consequence of the date is included. Every sentence earns its place, making it easy to scan.

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 mutation tool with five parameters and no output schema, the description covers the workflow, the validation rules, and the impact on lateness. It does not describe the response format or error behavior, but that is often standard for mutation tools. The only notable gap is that 'planned' is mentioned in the sequence but not in the status enum, which could confuse an agent, but this is a minor omission given the overall clarity.

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 schema already documents all five parameters. The description does not need to repeat that. It does add the sequencing of statuses and the note requirement for 'accepted', but the note parameter is optional in the schema, creating a slight mismatch. Overall, the description adds marginal semantic value beyond the schema, consistent with the baseline of 3 for high coverage.

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 ('Record a dated move') and identifies the resource ('one deliverable') and the lifecycle statuses (planned, in_progress, delivered, accepted). It clearly distinguishes this from sibling tools like deliverable_add (which creates) and deliverable_delete (which removes). The title also reinforces the action.

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 when to use this tool: when moving a deliverable along its status sequence. It mentions the order constraints and that a date before the reference document is refused, which tells the agent when the call may fail. It does not explicitly name alternative tools, but the sibling list makes it obvious this is the status-update tool, so the usage context is clear enough.

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 by stating the tool returns a DS-YYYY-NNNN number and listing the returned fields, as well as noting the free-tier limit of 3 open schedules. However, annotations are all false and provide no safety profile, so the description still does the heavy lifting; it does not disclose side effects, duplicate behavior, or what 'open' fully implies.

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 tight sentences with no filler. The core action and return value are front-loaded, and the free-tier constraint is a concise, relevant addendum. Every part of the description 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?

Together with the rich schema, the description covers the inputs and the primary return shape reasonably well. But it omits explicit creation semantics, idempotency or duplicate handling, and any error or limit behavior beyond the free-tier cap, so an agent still has to infer some call-time behavior. Adequate for a moderately simple create tool, but not complete.

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 86%, so the input schema already documents most parameters well. The description restates the reference types and return fields, but adds little beyond the schema; the free-tier note is not parameter-specific. This is an adequate baseline case where the schema carries the semantic weight.

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 states the action ('Open a delivery schedule'), the resource types it applies to (quote, work order, change order), and the key output (the DS-YYYY-NNNN number). It is clear about what the tool does, and the resource-scope helps set it apart from generic schedule tools, though it does not explicitly contrast with sibling get/list tools.

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?

There is no guidance about when to use this tool versus alternatives such as delivery_schedule_get or delivery_schedule_list. The description implies it is used for creating a schedule against an existing reference, but it does not state prerequisites, exclusions, or when a sibling tool 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 already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds meaningful behavioral context beyond this: non-empty schedules are refused with the offending deliverables named, the DS number is never reissued, and the operation is free on every tier. These details help agents anticipate failure modes and long-term side effects.

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 sentences with no wasted words. The primary action and precondition are front-loaded, followed by refusal behavior and a long-term consequence. Every sentence earns its place, and the structure is clear and direct.

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 destructive tool with full schema coverage and informative annotations, the description covers the essential operational context: what it does, when it fails, and the persistent effect of the deletion. It does not specify the success response format, but that is acceptable given the absence of an output schema and the simplicity of the operation.

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 input schema already describes the 'schedule' parameter with examples (DS-2026-0001, WO-2026-0001, or title), giving 100% coverage. The description does not add further parameter-level details, so the baseline of 3 is appropriate—the schema carries the semantic load.

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 ('Delete') and resource ('schedule') with a clear condition ('carrying no deliverables'), and distinguishes this tool from siblings by specifying it only applies to empty schedules. The alternative behavior for non-empty schedules is also mentioned, so an agent can tell this apart from related tools.

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 clearly indicates when to use the tool (to free an open slot by deleting an empty schedule) and when not to (if the schedule holds any deliverables, it will be refused). However, it does not explicitly name sibling alternatives, such as delivery_schedule_create or deliverable_delete, so it falls slightly short of the highest score.

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?

All annotations are false, so the description carries the full burden of disclosing side effects and operational details. It says 'render' but does not clarify whether this is a read-only operation, whether it modifies any state (e.g., marks a schedule as sent), or what happens if the schedule is not found. There is no mention of permissions, idempotency, or side effects. Given the lack of annotation hints, this is a significant gap.

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 main sentence is concise and informative, front-loading the core purpose. However, it ends with an unexplained 'Pro.' which appears to be a truncation or error, disrupting the structure and clarity. This stray token reduces the overall quality, making it less polished than a cleanly structured description.

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 tool with no output schema and no helpful annotations, the description should clarify the return value or behavior on error. It mentions the output is 'plain-text document' but does not specify whether the agent receives the text directly, a file reference, or something else. It also lacks behavioral notes (e.g., error handling, prerequisites). While the content list is useful, the missing operational details make it incomplete for safe and 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 description coverage is 100%, so the parameters (as_of, schedule) are already documented with their formats and meanings. The description adds context about the document contents ('counts as at a date' aligns with as_of) but does not provide any additional semantic detail beyond the schema. With full schema coverage, the baseline is 3, and the description does not meaningfully elevate 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 clearly states the action ('Render'), the resource ('one schedule'), and the output format ('plain-text document for the client'). It enumerates the content (deliverables, due dates, statuses, counts, sign-off block), which distinguishes it from sibling tools like delivery_schedule_get (which likely returns structured data) and delivery_schedule_list (which handles multiple schedules). No ambiguity about the tool's 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 phrase 'for the client' signals the intended use case (producing a client-facing document), and the verb 'render' contrasts with the data-retrieval semantics of delivery_schedule_get/list. However, it does not explicitly state when NOT to use it or name alternatives; an agent must infer that this is for human-readable output rather than structured data. This is clear context but lacks explicit 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?

With annotations all reporting false, the description carries the burden of explaining behavior. It adds value by stating that it returns 'every deliverable' with detailed fields, includes late status and totals, and names the as_of date actually used. This is useful behavioral context beyond the tool name, though it does not discuss permissions or error 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 compact and front-loaded. The first sentence conveys the main purpose and content; the second adds a useful behavioral guarantee about naming the as_of. 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?

Given there is no output schema, the description appropriately enumerates the return contents, including due dates, statuses, delivered/accepted dates, note, value, late items, and totals. It also covers the as_of semantics. It does not mention not-found behavior or ordering, but for this simple tool the core information is present.

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 schema already fully documents the required 'schedule' parameter and optional 'as_of' parameter. The description reinforces that 'as_of' is a date and that the response will reflect that date, but it does not add meaning beyond the 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 clearly states a specific action ('Return one schedule in full as at a date') and enumerates the exact content delivered, distinguishing it from delivery_schedule_list or late_report. The scope is unambiguous: one schedule, not a list or a filtered subset.

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 evident when to use this tool: when a complete, date-specific view of one schedule is needed. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for an agent to choose it over list or late-report tools.

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 describes a read-only listing operation, but the annotations set readOnlyHint=false, directly contradicting the description. Additionally, the description does not disclose any further behavioral traits such as pagination behavior, error handling, or the meaning of the trailing 'Free.' fragment.

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 main sentence is information-dense and front-loads the core listing behavior, but the final 'Free.' is ambiguous and unhelpful, detracting from clarity. The description could be better structured to separate the ordering/fields from the filters.

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 description covers the core behavior, ordering, and output fields, but it omits details about pagination/limit semantics and does not compensate for the missing output schema. The read-only annotation contradiction further undermines trust and completeness.

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 all five parameters are already documented in the input schema. The description adds context about sort order and the date-based counts, which aligns with as_of and state, but it does not substantially enhance parameter understanding beyond what the schema already provides.

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 states the verb 'List' and the resource 'schedules', and adds specificity with ordering ('oldest reference first'), returned fields (client, currency, counts), and filters (client, reference, state). This distinguishes it from sibling tools like delivery_schedule_get, which implies single-item retrieval.

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 explicit guidance is given about when to use this tool versus alternatives such as delivery_schedule_get or deliverable_status. The mention of filters and state values implies common use cases, but the description does not state conditions, exclusions, or preferred alternatives.

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 establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral detail beyond that: output is split between still-outstanding and delivered-late items, ordered worst first, aggregated by currency, and references without a schedule cause refusal.

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 carry substantial information with no filler. The core meaning is front-loaded, and each clause adds a distinct useful fact: scope, ordering, currency aggregation, delivery-late separation, and the refusal condition.

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?

Given the tool's moderate complexity, optional parameters, and absence of an output schema, the description provides enough context about result shape and error behavior to guide a call. It could be more explicit about the exact returned fields or refusal mechanism, but the annotations and well-described parameters cover the remaining safety and invocation concerns.

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 baseline is 3 even without description-level parameter help. The description adds some context for the reference parameter by stating that no matching schedule is refused, but it does not substantially enrich understanding of the other parameters beyond what the schema already provides.

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 exactly what the tool reports: deliverables still owed past their due date, ordered worst first, with value at risk per currency, and delivered-late items kept separate. This clearly differentiates it from sibling list/status tools, which cover schedules or deliverables without the late/as-of focus.

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 the tool is for as-of-date lateness reporting and notes an edge condition ('A reference with no schedule is refused'). However, it does not explicitly say when to choose this tool over siblings like delivery_schedule_list or deliverable_status, so usage guidance is mostly inferred rather than stated.

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.

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

Annotations declare readOnlyHint=false, meaning the tool is not read-only and may have side effects, but the description explicitly says 'Writes nothing,' which directly contradicts the annotation. No other behavioral detail (e.g., side effects, error cases) is provided; this is an annotation contradiction.

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 brief and front-loaded with the core action, but the trailing 'Pro.' is cryptic and adds no value, creating mild confusion. Otherwise, it uses two sentences with no wasted words, though the contradiction and unclear 'Pro' deductions keep it from being a perfect 5.

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, annotations that are not informative, and a description that contradicts them, the definition lacks critical context. It does not explain when to use this tool, what side effects (if any) exist, or how the units (MAJOR/MINOR) map to parameters. The contradiction further reduces the completeness.

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 each parameter (as_of, schedule, tax_rate, issue_date) has clear descriptions. The tool description adds no parameter-specific detail beyond mentioning VAT rate and units, which only loosely relate to tax_rate and the output structure. The schema carries the meaning, so the 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?

The description states a specific action ('build the delivered-and-accepted deliverables'), the target output format ('invoice_create-ready items' and 'quote_create-ready items'), and the units (MAJOR/MINOR). It clearly distinguishes this from sibling tools by referencing the payload purpose and the 'Writes nothing' behavior, so an agent can infer it generates data rather than modifying records.

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 a preparatory role for invoice_create and quote_create by naming those outputs, but it doesn't explicitly state when to prefer this tool over siblings like deliverable_add or delivery_schedule_get. The 'Writes nothing' hint is a safety cue, but no direct comparison or exclusion criteria are given.

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