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

With no annotations provided, the description carries the full burden and excels: it discloses irreversibility, the absence of de-anonymization, the exact data erased and kept, the server's refusal behavior for due invoices, and the risk of targeting the wrong customer. Every behavioral aspect is transparent.

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?

Although lengthy, every sentence serves a purpose: irreversibility, scope, GDPR rationale, uniqueness, usage constraints, confirmation requirement, and prerequisite. The 'WRITE, AND IRREVERSIBLE' opening is a strong front-loaded signal. No redundancy; thoroughness is justified for a destructive operation.

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 destructive irreversible operation, the description is complete: it covers action, effect, prerequisites, warnings, and operational guidance. No output schema exists, but as a write operation this is acceptable. An agent has all necessary information to safely and correctly invoke this tool.

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% with a clear description, so baseline is 3. The description adds significant extra meaning by emphasizing that the reference is the sole identifier and that a typo anonymizes a different customer, thereby stressing the parameter's criticality and caution required. This elevates it above baseline.

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 the precise action: erases personal data (name and email) of a ProAbono customer while retaining invoices and subscription history. It clearly identifies the resource and verb, and explicitly distinguishes itself as the only irreversible tool on the server, differentiating it from all siblings.

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 explicit usage context: use for GDPR erasure requests, never for test data cleanup, and requires developer confirmation before calling. It also states a precondition (no due invoices) and warns against misidentification due to typo. This is comprehensive 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?

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it discloses that the invoice is issued for real, that an immediate charge is attempted for customers on automated payment, and that the invoiced amount depends entirely on existing balance lines. This goes well beyond a generic 'creates an invoice' statement.

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 WRITE marker and core action appear first, followed by the balance-source dependency, the real-world charge behavior, and the recommended follow-up tool. Every sentence contributes useful guidance with no 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?

Given there is no output schema and no annotations, the description supplies the essential context an agent needs: what is invoiced, what happens if the balance is empty, the real payment side effect, and how to retrieve the resulting invoice/PDF. It is sufficiently complete 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?

The input schema already documents all six parameters with 100% coverage, so the baseline is 3. The description does not add parameter-specific detail beyond what the schema provides, though it does clarify the overall relationship between balance lines and the invoice amount.

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 ('Creates an invoice from the lines currently sitting in a ProAbono customer's balance') and clearly distinguishes the tool from siblings by naming create_balance_line and get_invoice. The WRITE prefix and title reinforce the operation's nature without 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 tells the agent when to use the tool in sequence: create_balance_line runs first to determine the amount, bill_customer invoices that balance, and get_invoice should be used afterwards. It also warns that billing an empty balance invoices nothing, giving a practical when-not-to 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?

No annotations are present, so the description carries the burden. It discloses the operation type ('WRITE'), the effect (creates a line, no invoice), sign/currency semantics, and the behavioral caveat that the entry merely sits in balance until bill_customer runs. This is strong, though it does not cover reversibility, permissions, or failure 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?

Four short sentences, each earning its place: intent, sign/currency, non-invoicing caveat, and use case. Front-loaded with 'WRITE' and the primary action.

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 no annotations and no output schema, the description provides the key contextual frame: what the operation does, what it does not do, and the required ordering with bill_customer. It omits response/return details and prerequisites, but the input schema fully covers parameters; an agent is adequately equipped for selection and 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 baseline is 3. The description adds segment currency context and reiterates sign meaning, but most parameter semantics (date/period exclusivity, ensure_billable, label) already exist in the schema. It does not substantially extend schema 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?

States a specific verb and resource: 'Creates a line in the balance of a ProAbono customer'. Clarifies debit/credit semantics and explicitly contrasts with bill_customer ('does not invoice'), distinguishing it from the closest sibling 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 names the alternative: 'bill_customer is what turns the balance into an invoice' and states sequencing ('only useful in that order'). Provides a concrete use case ('one-off charge or a goodwill credit that the catalogue does not cover'), which functions as a when-to-use instruction.

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?

No annotations are present, so the description carries the full burden. It discloses the write nature, the draft-vs-active state semantics, that a draft grants no rights, and that the subscription is a copy of the offer. It does not mention permissions, billing side effects, or idempotency, but the key state behavior is transparent.

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 dense and efficient, with the core purpose and 'WRITE' marker front-loaded. Each sentence carries useful information about state, activation, or alternatives. The override sentence is a minor extra that could mislead, but overall the structure is clean.

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 create tool with no annotations and no output schema, the description explains the essential state model and routes to activation. It doesn't specify return values, error conditions, or prerequisite offer/customer states, but the combination of description and a fully covered schema is adequate for an agent to invoke 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that the subscription is a copy of the offer and by describing the consequence of start_now (draft grants no rights). The mention of 'pass an override' is slightly confusing because no override parameter exists in the schema, but the added context is still useful.

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 a specific verb and resource: 'Creates a ProAbono subscription linking an existing customer to an offer.' It also distinguishes itself from the hosted subscription workflow and from start_subscription, which activates a draft. An agent can immediately tell this tool apart from its siblings.

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 contrasts the API path with the hosted workflow a customer would use, defines when to set start_now vs leave the subscription in Draft, and points to start_subscription for later activation. Clear when-to-use and alternative routes are provided.

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 no annotations, the description carries the full burden and does well: 'WRITE', idempotent upsert behavior, 'Only the fields passed are written', and the warning that name/language can be overwritten by hosted pages. It stops short of covering auth requirements, error modes, or response shape, but the key behavioral traits are disclosed.

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 sentences deliver a lot: action, upsert semantics, use cases, partial update, and a critical warning. It is front-loaded with 'WRITE. Creates...' and every sentence earns its place with no 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 write tool with no output schema and five parameters, it provides enough context for correct invocation: when to use, upsert behavior, partial update, and the hosted-pages overwrite pitfall. It omits response/error details, but those are secondary to calling the 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?

Schema coverage is 100%, so baseline is 3. The description adds real value by stating partial-write semantics and warning about field authority, directly affecting how name and language should be handled. It does not need to repeat schema details, but the added guidance pushes it above baseline.

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 'Creates a ProAbono customer... or updates it when one already carries that reference' and explicitly calls out the upsert keyed on ReferenceCustomer. This makes the tool's dual create/update job unambiguous and distinguishes it from read-only siblings like get_customer and update_billing_address.

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 gives concrete trigger points: 'first provisioning at sign-up or first login' and 'every later change', with a rationale about hosted pages and rights reads. It does not explicitly name alternative tools or state when not to use it beyond the field-authority caution, so it misses the top tier by a small margin.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It discloses several important behaviors: no per-language SDK exists, Basic auth is read from configuration, the Segment is carried, collections are read to TotalItems, 204 is handled, unrecognized languages get HTTP calls instead of code, and the tool names task-specific generators when applicable. It does not disclose rate limits or error behavior beyond the language fallback, but the disclosed behaviors are substantial and specific.

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 dense paragraph, front-loaded with the core action and then detailing return contents and usage routing. Every sentence earns its place, though the long list of return items ('authenticated client... operations... guardrails') is somewhat packed. It is appropriately sized for a complex code-generation tool.

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 complex tool with no output schema and no annotations, the description is quite complete: it explains what the generated code includes, how authentication works, how collections are handled, and how to choose between this tool and task-specific siblings. It does not describe the exact output format or error cases beyond the language fallback, but the essential context for correct invocation 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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining what the task parameter is used for (drives which operations and guardrails are returned) and what the language parameter's fallback behavior is (unrecognised languages get HTTP calls, never another language's code). This goes beyond the schema's examples and adds real selection guidance.

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 ('Generates code'), a specific resource ('for a ProAbono task'), and a specific input ('in the language you name'). It also distinguishes itself from siblings by naming the task-specific generators it is not (portal, pricing table, workflow round trip, rights cache, webhook endpoint). An agent can tell it apart from generate_pricing_table and scaffold_notification_endpoint 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?

The description explicitly says when to use it: 'Use it for a task no task-specific generator covers', and names the alternatives: 'where one does — the portal, the pricing table, the workflow round trip, the rights cache, the webhook endpoint — it says so and names it'. This is explicit when/when-not guidance with named siblings.

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 no annotations, the description carries the burden of behavior disclosure. It does disclose that the identified flavour requires a customer reference and security hash, and that post-selection behavior is configured in the BackOffice. It does not mention output format, side effects, or any authentication requirements beyond the security hash, leaving some behavioral gaps.

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 tight sentences with no filler. It front-loads the core action, then efficiently explains modes and external configuration. Every sentence contributes value.

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 two modes and external config, but no output schema or annotations exist. It leaves unclear how the customer reference and security hash are supplied since they are absent from the input schema, and it doesn't describe what the generated embed looks like. These are notable gaps for a tool with no structured fallback.

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. The description adds real meaning to the 'identified' parameter by explaining the two flavours and the subscribe-in-place implication. The note about customer reference and security hash adds context, even though those values are not schema parameters.

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 ('Generates') and resource ('the embed that renders the ProAbono pricing table'), making the tool's function clear. It does not explicitly distinguish it from siblings like install_customer_portal, but the verb+resource combination is sufficiently distinct.

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 gives clear context for when to use the anonymous vs identified flavour, and notes the dependency on customer reference/security hash for the identified case. However, it does not mention when to prefer a sibling tool or provide any explicit exclusions, so guidance for alternative selection is missing.

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?

No annotations are provided, so the description carries the transparency burden. It discloses that the tool returns contract information rather than making the API call, and it enumerates what the contract contains: parameters, required flags, request body schema, and responses. It does not cover edge cases like missing or conflicting arguments, but this is a minor gap for a lookup 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?

Two sentences with no filler. The first sentence states what the tool returns, the second explains when to use it. Every clause 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 two-parameter lookup tool, the description covers the return value, the lookup modes, and the recommended usage context. A small ambiguity remains because both parameters are optional in the schema and the description does not explicitly require one, nor does it describe the behavior if both or neither are passed.

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 both params at 100% coverage, so the baseline is 3. The description adds useful context by framing them as alternate lookup modes ('endpoint or object') and giving additional object examples, but it does not specify whether both params can be supplied together or what happens if neither is provided.

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 ('Returns the exact contract') and names a clear resource: a ProAbono API Live endpoint or a named object like Customer, Subscription, Offer, Feature, or Usage. It distinguishes this meta-lookup tool from the many sibling tools that perform actual API operations.

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 says to use this tool before calling or generating a call to the ProAbono API, so parameter names and shapes come from the contract rather than memory. It does not name alternative tools or state when not to use it, but the intended context is clear.

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 no annotations provided, the description carries the burden, and it explicitly states 'Read-only' as a behavioral guarantee. It also discloses domain significance (address used for invoices, tax identifier driving VAT treatment), which helps the agent anticipate how the result will be used. It does not cover error cases or auth requirements, but for a simple read it is reasonably transparent.

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 action, followed by the field list, the read-only caveat, and the practical usage rationale. Every sentence contributes useful information, and there is no repetition or 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 single-parameter read tool with no output schema and no annotations, the description is largely complete: it lists return fields, states the operation is read-only, and explains why the data matters. It could further describe error behavior or absence of a billing address, but the essential agent decision context 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 description coverage is 100%, so the single required parameter customer_ref is already fully documented. The description adds no additional parameter-level detail, but it does not need to; the baseline of 3 applies when the schema handles parameter semantics completely.

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 ('Reads') and a concrete resource ('the full billing address of a ProAbono customer'), then enumerates the exact fields returned. It clearly differentiates from siblings like get_customer and update_billing_address by emphasizing the read-only, billing-address-specific scope.

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 explicit context for when to call it: before deciding whether a billing-address update is needed, and notes the billing address is what invoices are issued against. It does not explicitly name alternative tools such as get_customer, but the update-focused usage guidance is clear enough for an agent to select it appropriately.

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?

There are no annotations, so the description carries the full behavioral burden. It discloses the operation is read-only, describes what the return includes (TypeCredit, Reason, amounts, PDF URL), and explains the important edge case where naming a debit invoice causes the tool to say so rather than misrepresent it. This is substantial behavioral context for a simple retrieval 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?

The description is dense but not padded. It front-loads the main purpose, then immediately covers return contents, read-only behavior, identifier usage, the endpoint edge case, and the sibling alternative. Every sentence contributes actionable 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?

With no output schema, the description appropriately enumerates key return elements and even notes where the PDF URL comes from. It covers identifier conflict, wrong-target behavior, and alternative routing. For a two-parameter read-only retrieval tool, nothing an agent needs to call it correctly is missing.

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 at 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema by stating exactly which identifier concepts map to the parameters and by adding the mutual-exclusion rule: pass one, not both. That extra guidance justifies above-baseline scoring without reaching 5.

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 starts with a specific verb and resource: 'Retrieves one ProAbono credit note with all its detail.' It differentiates from get_invoice by explicitly noting that a debit invoice should be fetched with get_invoice, and it clarifies the credit-note-as-invoice relationship. An agent can immediately understand what this tool returns and how it differs from close siblings.

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 gives explicit selection guidance: use get_credit_note for credit notes and get_invoice for debit invoices. It also specifies identifier usage requirements: 'Identify it by internal identifier or by full number; pass one, not both.' This leaves no ambiguity about when and how to invoke the tool.

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?

No annotations are provided, so the description carries the behavioral burden. It explicitly says 'Read-only' and describes that the result includes Links, which gives an agent useful safety and response-shape information. It does not specify missing-customer behavior or auth requirements, but for a simple getter this is a minor 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?

Two sentences with no filler: the first states what is retrieved and by what key, the second adds safety and a use case. It is front-loaded and every sentence contributes.

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 low complexity, full schema coverage, and no output schema, the description covers the main identifier, the Links in the response, read-only behavior, and a concrete use case. It falls slightly short on error or not-found semantics, but overall it gives an agent enough to call the 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?

Schema description coverage is 100%, so the baseline is 3. The description adds mild context by referring to customer_ref as the 'reference shared with the merchant's application (ReferenceCustomer)', but it doesn't materially explain offer_ref 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 a specific action with a clear resource: 'Retrieves a ProAbono customer by the reference shared with the merchant's application.' It also adds the distinguishing detail that the response includes hosted-page Links, separating it from sibling tools like create_customer or update_customer.

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 gives an explicit use case: 'Use it to check whether a logged-in user already exists as a ProAbono customer.' It doesn't mention when not to use it or name alternative tools, but the context is clear enough for an agent to choose it appropriately.

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 no annotations, the description carries the full burden and does so thoroughly. It discloses read-only nature, source of PDF URL ('from the document's own Links'), and the special handling of credit notes. No contradictions.

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 concise sentences, front-loaded with the core function, then details. Every sentence adds value (scope, identification rules, differentiation, edge-case behavior) with no 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 retrieval tool with no output schema and no annotations, this description is complete: it specifies what is returned (detail, PDF URL), how to identify the invoice, and what happens on mismatch. Nothing essential is missing.

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 baseline is 3. The description adds the mutual-exclusivity constraint ('pass one, not both') and clarifies that full_number is as printed with an example. This is valuable beyond the schema, though the schema already documents the parameters well.

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 a specific verb+resource ('Retrieves one ProAbono debit invoice') and enumerates the included details (status, amounts, dates, payment method, note, PDF URL). It also differentiates itself from get_credit_note explicitly, making its scope unambiguous.

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 explicit guidance: 'pass one, not both' for the two identifiers, and names the alternative tool (get_credit_note) for credit notes. It also explains behavior when the identifier resolves to a credit note, giving clear conditions for use.

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 no annotations provided, the description carries the transparency burden. It explicitly states 'Read-only,' which is important for an AI agent's safety assessment, and it describes the returned data (Features, pricing, Links). No contradictions or hidden side effects are suggested.

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, purposeful sentences: what it does, safety property, and when to use it. Every sentence adds value and the key 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 simple single-offer retrieval with one required parameter, the description is complete enough: it covers the operation, the read-only nature, the main return contents, and the usage condition. Since there is no output schema, mentioning Features, pricing, and Links helps the agent understand expected results.

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 fully documents offer_ref and customer_ref. The description adds little beyond 'by its reference' and does not explain the customer_ref direct-subscribe-link behavior, but the schema covers that detail adequately.

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: 'Retrieves a single ProAbono offer by its reference.' It also names what is included (Features, pricing, Links), which clearly distinguishes it from list_offers by emphasizing the singular, reference-based lookup.

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 sentence 'Use it when the offer reference is already known' gives explicit context for when to invoke this tool. It implies that list_offers is the alternative when the reference is unknown, though it does not name the sibling tool explicitly.

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 no annotations provided, the description must carry the behavioral burden, and it does so by explicitly declaring 'Read-only' and listing the data fields included in the response. It also explains that this tool aggregates settings that the set_* tools each modify, which is informative beyond the schema. It does not mention authentication or error behavior, but for a simple read on a single reference this is a minor 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 description is two sentences with no filler. The first sentence states the action and enumerates the returned fields; the second sentence reinforces the read-only nature and links to the mutating tools. Every clause earns its place and key 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 single-parameter read tool with no output schema, the description provides the essential return contents and explicitly frames the tool in relation to its writing counterparts. An agent can correctly infer what to expect and when to choose this tool. Nothing critical for a basic call is missing.

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 only parameter, customer_ref, is already fully described in the schema with 100% coverage, so the description does not need to add syntax or format details. The description focuses on the return content rather than the parameter, which is appropriate. This matches the baseline of 3 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 opens with a specific verb and resource: 'Reads the payment settings of a ProAbono customer in one call.' It enumerates the exact fields (payment type, billing mode, grey-list status, invoice note, next billing date), making the tool's scope unmistakable. It also names the sibling write tools, so an agent can distinguish this read operation from the set_* family without inspecting those 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?

The description explicitly labels the tool as read-only and points to set_payment_method, set_invoice_note, and set_next_billing_date as the tools that write the same fields. This gives clear direction for when to use this read endpoint versus its mutation siblings. It stops short of formal 'use this when... not when...' phrasing, but the context is strong enough for an agent to route correctly.

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 no annotations, the description carries the full burden of behavioral disclosure. It meaningfully discloses that the tool returns only variable names and never exposes keys, secrets, or account identifiers, which is important safety context. The read-only nature is implied by 'Reports' and 'confirms', though not explicitly stated as non-mutating.

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 short sentences, each earning its place: the first states functionality, the second provides a safety guarantee, and the third gives usage guidance. It is front-loaded with the most important information and contains no 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 zero-parameter, read-only health check, the description is complete: it explains what is returned, makes an important privacy guarantee, and tells the agent exactly when to invoke it. No output schema exists, but the description sufficiently outlines the return content for correct use.

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 tool has zero parameters)Skip the description cannot add parameter-level details. The schema already covers 100% of parameters (none), and the description adds relevant contextual meaning about what the tool returns, satisfying the baseline for no-parameter tools.

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 ('Reports', 'confirms') to identify the resource: the ProAbono MCP Installation server's version and configuration status. It clearly differentiates this tool from sibling tools by focusing on server health, not subscriptions, customers, offers, or documentation.

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 states when to use the tool: 'Use it to check the server is reachable and configured before running an installation.' It does not name alternatives or when-not-to-use conditions, but given the tool's unique health-check role among siblings, the guidance is sufficiently clear.

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 no annotations provided, the description carries the full burden. It explicitly declares 'Read-only', which is a critical safety cue. It also discloses the resolution logic (default to current subscription if subscription_id omitted) and that it returns state/dates/Features. It does not mention error behavior or what happens if no subscription exists, but for a simple read this is adequate.

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 and front-loads the purpose and read-only note before diving into parameter logic. Each sentence adds value: purpose, access constraint, and alternative. Slightly wordy in the second sentence but acceptable and well-structured.

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 read tool with three parameters and no output schema, the description covers the core behaviors: what it returns, how to address a specific subscription, and the default behavior. It lacks explicit error handling notes and a detailed return format, but given the simplicity and the sibling pointer, it is sufficiently complete for an agent to call 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 coverage is 100%, so the schema already documents all three parameters. The description adds meaningful context: it explains why customer_ref is required (access path), what subscription_id does when omitted (default to current), and what offer_ref narrows to. This goes beyond the schema's bare descriptions and clarifies usage 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 uses a specific verb ('Retrieves') and names the resource ('one ProAbono subscription of a customer'), plus the fields it returns (state, dates, Features). It clearly distinguishes itself from the sibling list_subscriptions by explaining the singular retrieval scope and the customer-based access path.

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 explains when to use this tool: it is the only way to retrieve a subscription (no retrieve-by-identifier), requires customer_ref, and explains the optional subscription_id and offer_ref parameters. It also directs the user to list_subscriptions for seeing all, giving a clear alternative.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It declares the operation read-only, clarifies that results reflect ProAbono's current view, and exposes a subtle behavior: an empty result is ambiguous rather than definitive. This is strong behavioral context for a read-only lookup.

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, each earning its place: the definition, the usage distinction, and the empty-result caveat. The most important semantics are front-loaded and there is no 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 simple two-parameter read tool with no output schema, the description covers purpose, behavior, and the key empty-result ambiguity. It could further describe the per-entry fields or error cases, but an agent has enough to invoke it correctly and interpret the main outcome.

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 customer_ref and feature_ref. The description adds context around what a Usage is and how entries relate to Features, but it does not add new parameter-level details beyond the schema. 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 verb and resource: 'Reads a customer's Usages' and defines what that means semantically: what the customer may do right now, one entry per Feature in running subscriptions. It also distinguishes the tool from the offer reference and from list_subscriptions, giving an agent enough to tell it apart from siblings.

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 says this is the source an application gates access on, and warns not to use the offer reference instead. It also gives concrete conditional guidance: an empty result is ambiguous, so check the customer's subscriptions with list_subscriptions before concluding they have no rights.

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 no annotations, the description carries the behavioral disclosure burden. It clearly signals a read operation by saying it 'reads' a file and reports status, and it proactively clarifies that a never-installed project is reported as an answer, not a failure. It could be more explicit about having no side effects, but the language strongly implies read-only 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 information-dense and well-structured: purpose and output scope first, usage guidance second, and an important edge-case clarification last. Every sentence contributes meaningful guidance without wasted words.

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 status-reading tool with one optional parameter and no output schema, the description explains what the tool reports, when to call it, and how a missing installation is handled. It does not describe the exact response format, but the behavioral categories given are sufficient for an agent to invoke and interpret the result 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 single parameter `project_root` has 100% schema description coverage, including its default behavior and when to pass it. The tool description does not add parameter detail beyond the schema, so the baseline of 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 verb and resource: it reads `.proabono/installation.json` and reports installation status. It enumerates the exact categories of information returned, which clearly separates it from sibling tools like `install_insite` and `verify_insite_installation`.

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 gives explicit usage timing: call at the start of a session before generating anything, and whenever a developer asks what is left to do. It does not explicitly name alternatives or exclusions, but the context is clear enough to guide selection among siblings.

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?

No annotations are provided, so the description must convey behavioral traits. It discloses that the tool returns three artifacts (security hash, route, snippet) and that it requires an authenticated customer area. However, it doesn't mention side effects like filesystem writes (e.g., .proabono/installation.json) or whether it modifies the project, which is a gap for a code-generation tool. It does imply a multi-environment need but stops short of fully disclosing operational impact.

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 tight 3-sentence block with the main purpose front-loaded and return artifacts listed early. The prerequisite is a single clause. There is no filler; every sentence earns its place, making it efficient and 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?

Given the tool's complexity (5 params, code generation, 3 return artifacts) and no output schema, the description covers the key usage context: the installation step, the requirements, and what the output includes. It lacks explicit mention of side effects like filesystem writes or the need to run in the developer's project, but the context signals suggest an MCP environment, which partially mitigates this. Overall, it is nearly complete for an agent to correctly invoke.

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 all parameters. The description adds some context about the overall purpose but does not add additional meaning beyond the schema. For example, it doesn't explain the trade-offs of 'record_state' or 'pass_language' beyond their names. Baseline is 3, which 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 clearly states the verb 'Install' and the resource 'ProAbono Customer Portal', and specifies what the tool generates (code embedding the portal) and its scope (in a page of the merchant's site). It also differentiates from siblings by focusing on the in-site installation step, not on other portal-related operations like creating subscriptions or managing offers.

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 names this as 'step 1 of the In-Site installation', provides a prerequisite ('Requires an authenticated customer area'), and contrasts with hosted pages. It tells when to use it and implicitly guides against using it for other portal setups. The description is clear about the deployment context, leaving no ambiguity about when to select this tool.

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 no annotations provided, the description carries the full burden of behavioral disclosure, and it does a thorough job. It discloses side effects: 'records progress in .proabono/installation.json' and 'writes no source file of yours.' It also reveals the execution model: detects stack, checks four prerequisites before generating, runs three steps in order, and resumes instead of starting over. It clarifies what the tool returns ('generates code and returns it'). This is rich, honest behavioral transparency for a complex orchestrator.

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 long but information-dense: every clause adds value (main action, prerequisite checks, steps, side effect, usage trigger, exclusion, return behavior). It front-loads the core purpose and then details the process. However, it is structured as a few very long run-on sentences, which could be broken into shorter, more scannable sentences. Minor deduction for readability, but no wasted words.

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 complex orchestration tool with no annotations and no output schema, the description is quite complete: it explains the full sequence, the prerequisites, side effects, and when to call. It does not state what happens if prerequisites fail, whether user confirmation is needed for the stack hypothesis, or the exact return format, but the schema already covers 'Ask the developer' for target_page and customer_area. The main omission is failure/abort behavior and how the agent should handle prerequisite failures. A more thorough tool would mention that, hence 4.

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. The description provides narrative context for parameters (e.g., 'detects the stack' for the `stack` parameter, 'authenticated customer area' for `customer_area`, 'how a ProAbono customer will exist' for `provisioning`), but it does not add concrete parameter-specific semantics beyond what the schema already states. It does not compensate by explaining formats, defaults, or relationships among parameters in a way the schema omits.

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: 'Orchestrates the whole In-Site installation', then details the exact sequence (detect stack, check prerequisites, run three steps). It also distinguishes itself from siblings by being the end-to-end orchestrator that 'runs the three steps in order' (Customer Portal, Subscription Workflow, rights synchronization), corresponding to sibling tools like install_customer_portal and link_subscription_workflow. It additionally clarifies it never offers Widget/plug-in installs, making the scope unmistakable.

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 tells when to use it: 'Call it when a developer asks to install, set up or integrate ProAbono.' It also gives a clear exclusion: 'It installs ONE way, In-Site by code: it never offers a Widget or a plug-in.' This tells the agent when NOT to use it. The orchestration order and prerequisite checks further imply that if only a single step is needed, the appropriate child tool should be used, though not stated by name. Still, the trigger condition and exclusion are explicit enough for correct selection.

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?

No annotations are provided, so the description carries the disclosure burden. It does disclose meaningful behaviors: it reads the account's real offers, returns a BackOffice redirect URL, and writes installation state unless record_state is false. However, the write behavior is already documented in the record_state parameter schema, and the description omits other potential side effects like network/auth requirements or exact filesystem changes, leaving some gaps.

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 dense, run-on paragraph with a confusing placeholder-like phrase 'branches on from x outcome for all five outcomes.' It repeats information already in the schema (writes installation state unless record_state is false) and embeds code snippets inline, making it harder to parse than necessary. This is over-specification without clear structure, not concise front-loading.

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 complexity (6 params, no output schema, no annotations), the description covers the main outputs and side effects but leaves key details unclear: the ambiguous 'x outcome', the exact format of the returned redirect URL, and what the generated code includes beyond the listed items. It is reasonably complete but not self-sufficient for an agent to predict all call results.

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% with each parameter described, so the baseline is 3. The description adds some contextual color (e.g., reading account offers relates to offer_ref validation) but largely repeats the schema's parameter descriptions rather than adding new meaning. Since the schema already does the heavy lifting, a 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 clearly states it generates the round-trip code for In-Site step 2, enumerating specific outputs (server-side fetch code, ProAbonoPortal.open, ?pa_query= link, return route, BackOffice redirect URL) and concrete use cases. It does not explicitly name sibling tools, relying on 'In-Site step 2' and the use-case list to differentiate, so it stops short of a 5.

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 provides explicit usage context: 'Use it for sign-up, plan change, restart, registering a payment method or paying an invoice.' This tells an agent when to invoke the tool, but it offers no when-not-to-use guidance or names alternative tools (e.g., install_insite, install_customer_portal), so it lacks full exclusion/alternative coverage.

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?

Since no annotations are provided, the description carries the burden of behavioral disclosure. It explicitly says 'Read-only' and 'Reads every page,' which are valuable beyond the schema. It does not mention rate limits or response details, but for a simple listing operation the key behavioral traits are covered.

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, then adds only high-value context: feature types, read-only nature, access-gating relevance, and pagination behavior. Each sentence contributes meaning without unnecessary 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 list tool with one optional parameter and no output schema, the description covers the resource, its types, the read-only safety profile, pagination, and the relationship to related tools. It could name the explicit return shape more fully, but the essential information an agent needs to invoke it correctly 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 single parameter visible_only is already documented in the schema. The description does not add extra semantic detail about the parameter, but it does not need to because the schema already explains it adequately.

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 verb ('Lists') and resource ('ProAbono Features of the account'), and clarifies that these are the business-owned definitions. It also distinguishes Features from customer-level Usages, referencing get_usages as the sibling tool, so the agent can tell them apart.

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 conceptual context: Features are definitions used for access gating, and a customer's value for a Feature is a Usage read via get_usages. This implies when list_features is appropriate, though it does not explicitly state exclusions or alternative selection criteria beyond the get_usages contrast.

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 no annotations, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only', 'Reads every page' (pagination behavior), explains the TypeCredit indicator semantics, and notes that the returned count is the customer's full history. It also discloses that the tool returns data 'as the Live API returns them', covering the raw format. This is thorough for a list 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?

The description is multi-sentence but every sentence adds value: it opens with the core purpose, then explains the TypeCredit distinction, read-only nature, filter limitation, and pagination. It is front-loaded with the primary action and does not waste words, though it could be trimmed slightly without losing critical 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?

Given no output schema, the description explains the return semantics (TypeCredit distinguishes kinds) and the pagination behavior ('Reads every page'), plus the full-history count. It covers the key aspects an agent needs to interpret results correctly. It does not detail error cases or exact response fields, but that is acceptable for a list tool without an output schema.

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 has 100% coverage for both parameters (customer_ref and subscription_id), so the baseline is 3. The description does not add significant meaning beyond the schema; it reiterates that they restrict to a customer or subscription but provides no additional syntax or format details. It does add context about the overall behavior, but not parameter-specific 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 clearly states the verb 'lists' and the resource 'billing documents of a ProAbono customer', and explicitly distinguishes between debit invoices and credit notes via TypeCredit. It is specific enough to differentiate from sibling tools like get_invoice and get_credit_note, which handle individual documents.

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 provides clear context: this tool returns both invoice types together, and notes that there is no kind filter, advising the caller to filter the list themselves if only one kind is needed. It also mentions the count reflects the full document history. However, it does not explicitly name alternative tools for single-document retrieval, leaving some inference to the agent.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly states 'Read-only' and reveals pagination behavior with 'Reads every page, not just the first,' which is valuable context beyond the schema. It does not mention response size or potential cost of reading every page, but for a read-only catalogue listing this is a 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?

The description is front-loaded with the core function, then efficiently adds use cases, the sibling alternative, and an important pagination trait. Every sentence contributes information needed for correct selection and invocation, with no 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?

With no output schema, the description compensates by summarizing the return contents: the offers, their Features, and pricing. It also covers scope, read-only behavior, pagination, and alternatives. It does not describe the exact response shape, but for a low-complexity list operation the provided context is nearly 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?

The input schema already documents the single optional visible_only parameter with 100% coverage. The description does not add parameter-level semantics, but the high schema coverage means the baseline of 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 and resource: lists the ProAbono offers exposed by the configured Segment, including features and pricing. It explicitly distinguishes itself from the sibling list_offers_for_customer by name, so an agent can tell them apart at a glance.

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 gives concrete use cases: showing a pricing page, selecting an offer for a subscription or pricing table, and validating the prerequisite that at least one offer with a Feature exists. It also gives an explicit when-not-to-use instruction, pointing to list_offers_for_customer for customer-specific or subscription-specific offer queries.

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 no annotations provided, the description carries the full burden. It explicitly states 'Read-only.' and 'Reads every page,' disclosing the operation's safety and pagination behavior. It also clarifies that results account for existing holdings, which is a key behavioral nuance. It does not mention rate limits or error handling, but for a read-only list operation, the disclosed traits are sufficient.

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 the core purpose first, followed by usage differentiation and a behavioral note. Every sentence adds value: purpose, when to use the upgrade_only variant, and pagination behavior. No fluff 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 the tool has 4 parameters (1 required), no output schema, and no annotations, the description covers the essential usage scenarios, differentiates from the sibling, and notes pagination. It does not describe the return format or error conditions, but these are often inferred for a list operation. The description is complete enough for an agent to invoke it correctly in most cases.

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 parameters are already documented. The description adds meaningful context by explaining how upgrade_only and subscription_id work together to retrieve upgrade/downgrade options, and notes the caveat about customers holding several subscriptions. This goes beyond the schema's individual descriptions. The other parameters (customer_ref, visible_only) rely on schema alone, which is acceptable given full 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 clearly states the verb 'lists' with a specific resource 'the ProAbono offers a named customer may take right now' and explicitly differentiates from the public catalogue. It also names the sibling 'list_offers' as the alternative, making the purpose unmistakable.

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 explicit guidance on when to use this tool vs the sibling: 'Use list_offers for the public catalogue.' It also explains the specific scenario for upgrade_only and subscription_id, including when to set them (when the customer holds several subscriptions) and what answer they yield. No ambiguity remains.

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 no annotations provided, the description carries the full disclosure burden. It clearly states 'Read-only' and adds the behavioral detail 'Reads every page,' which is genuinely useful for an AI agent. It does not cover error behavior or response shape, but for a simple read tool this is solid.

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 with no fluff. The core action and scope are front-loaded, read-only safety is stated immediately, and every sentence adds 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 one-optional-parameter, read-only listing tool, this is nearly complete: it names the resource, the filter, the content of results, and pagination behavior. The lack of an output schema means the exact return shape isn't described, but the stated 'state and Features' gives an agent enough to judge suitability.

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%: the only parameter, customer_ref, is already documented in the schema. The description restates that the parameter optionally restricts to one customer, adding little beyond the structured definition. 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 names a specific resource ('ProAbono subscriptions') and a precise action ('Lists'), with scope qualifiers ('optionally those of one customer'). It also clarifies what data is included ('state and the Features they carry'), which distinguishes it from siblings like list_offers and list_features.

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 gives explicit use cases: 'see what a customer is actually subscribed to' and 'explain why a customer has no rights.' It stops short of naming alternatives or saying when not to use this tool, but the intended context is clear.

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 no annotations, the description must carry the behavioral burden, and it does: it declares the tool is purely informational ('It plans and executes nothing'), describes the return value as an ordered plan naming the generating tool and human BackOffice tasks, and even explains why it mirrors install_insite. No hidden side effects or misleading promises.

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 dense but every sentence earns its place: it defines the return value, lists the journeys, clarifies non-execution, distinguishes from install_insite, and gives explicit call conditions. The most important facts are 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 single-parameter planning tool with no output schema and no annotations, the description is complete. It tells the agent what will be returned, what will not happen, when to use it, and how it relates to sibling tools. There is no important missing context that would prevent correct selection or 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?

The input schema already has 100% description coverage, with a well-documented enum for journey, so the baseline is 3. The description lists the five journey types but adds no meaning beyond what the schema provides. It does not need to compensate, because the schema already explains each enum value.

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 ('Returns the ordered plan') and names the exact resource (a named ProAbono journey), listing the five journeys. It also distinguishes itself from code-generation siblings by stating 'It plans and executes nothing' and by naming the tool that generates each step.

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: when a developer asks what the steps are, what order they go in, or what they are in for, before code is generated. It also clarifies that it does not execute anything, and explains how it relates to install_insite for the In-Site installation journey.

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 no annotations, the description carries the full load and does well: it flags WRITE, discloses idempotency ('the value is absolute, so repeating the call is harmless'), and explains the business semantics that IsEnabled (not IsIncluded) is what the application must enforce. It omits auth/permission requirements and failure modes, which keeps it short of a 5.

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?

Front-loaded with 'WRITE.' followed by purpose, then alternatives, then behavioral notes. Dense but every clause carries information; the parenthetical gloss of 'OnOff Feature' is mildly redundant but the overall structure is efficient.

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 no annotations and no output schema, the description covers the crucial decision inputs: which feature types it applies to, what the alternatives are, idempotency, and the quote-first precondition. Return values are not needed without an output schema; only permission/auth context is missing.

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 every parameter (including date_stamp, feature_ref, customer_ref, subscription_id) is already documented in the schema. The description reinforces the meaning of is_enabled as an absolute switch but adds no syntax or format detail beyond the schema; the baseline of 3 applies.

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 a specific verb (enables/disables) applied to a specific resource (an OnOff Feature in a customer's active subscription). It explicitly separates itself from the two sibling write tools (push_usage_increment for metered, push_usage_quantity for Limitation), so an agent can route correctly without opening a 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?

Gives an explicit constraint ('OnOff Features only'), names the alternative tools and the feature types that select them, and adds a prerequisite ('Quote it first with quote_usage_change when enabling is billable'). When-to-use, alternatives, and a precondition are all present.

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 no annotations, the description carries the full burden and does so well: it discloses the additive (non-idempotent) semantics, that a repeated call double-counts, that no absolute/idempotent fallback exists, and that retry-after-timeout is the caller's responsibility. That is exactly the behavioral risk an agent needs before invoking.

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?

Front-loaded with the operation type and core semantics, then alternatives, then the double-count warning and the quoting step. Dense but every sentence earns its place; no 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 5-param mutation with no annotations and no output schema, the description covers when-to-use, sibling disambiguation and the critical idempotency caveat. It does not mention required permissions/auth or what the call returns, which are minor gaps but real for a write endpoint.

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 increment, date_stamp, feature_ref, customer_ref and subscription_id parameters are already documented. The description reinforces the delta-vs-running-total meaning of increment and the notion that date is the consumption timestamp, but adds little that the schema does not already say. Baseline 3 applies.

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 operation type ("WRITE"), the verb (adds an increment) and the exact resource (Consumption Feature quantity of a customer), with concrete examples (messages sent, API calls, gigabytes stored). It also explicitly names the sibling tools it is not (push_usage_quantity, push_usage_enabling), so an agent can select it without opening any 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?

Explicitly routes the agent: consumption Features with this tool, Limitation Features with push_usage_quantity, OnOff with push_usage_enabling, and pre-quoting with quote_usage_change when billable. Conditions and alternatives are both stated, leaving nothing to inference.

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 no annotations, the description carries the behavioral burden and does well: it discloses that the value is absolute, that repeated sends are harmless (idempotent), and that it bills on provisioned seats rather than occupied seats. It omits auth/permission requirements and error behavior, but for a no-annotation write tool this is a 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?

Front-loaded with 'WRITE.' and the core action, followed by tightly packed sentences that each add a distinct fact (billing semantics, idempotency, sibling routing, quote precondition). No filler sentences.

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 5-parameter write tool with no output schema, the description covers purpose, alternatives, idempotency, and quantity semantics well. It could still mention permissions or failure modes, but per the rubric it need not explain return values since no output schema exists.

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; the description earns above that by clarifying the quantity semantics beyond the schema ('seats bought and not the seats occupied: that is what ProAbono bills on') and reinforcing that the value replaces rather than increments. It does not further explain customer_ref, feature_ref, or subscription_id.

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 a specific verb and resource ('Sets the current quantity of a Limitation Feature of a customer to an absolute value') and gives concrete examples (seats, projects, users). It explicitly distinguishes itself from siblings push_usage_increment and push_usage_enabling, so an agent can route correctly without opening other 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?

Gives explicit when-to-use rules: Limitation Features only, with named alternatives for metered Features (push_usage_increment) and OnOff Features (push_usage_enabling). It also states a precondition ('Quote it first with quote_usage_change when it is billable'), leaving little to inference.

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 no annotations, the description carries the full burden and does well: it declares read-only semantics ('nothing is written') and explains the two result modes (current charge vs. recurring cost with next_term). It doesn't cover authorization requirements or rate limits, and the future-date restriction lives only in the schema.

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?

Dense but front-loaded, starting with the core purpose and read-only guarantee. The sentences are long and pack multiple clauses, but every clause carries information an agent needs.

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?

No output schema and no annotations, yet the description compensates by describing what is returned (current charge, and recurring cost when next_term is set) and the sequencing relative to the write tools. Minor gaps remain on the exact response shape but nothing critical is missing.

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, but the description adds a genuine cross-parameter constraint absent from the schema: 'Pass exactly one of increment, quantity_current or is_enabled, matching the Feature's type.' That mutual-exclusivity and type-matching rule is real added value.

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 a specific verb and resource ('Prices an intended Usage change without applying it') plus a secondary function ('checks that it is allowed'). It clearly separates itself from the push_* siblings by naming them as the write operations it precedes.

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 says when to call it ('before push_usage_increment, push_usage_quantity or push_usage_enabling whenever the change is billable') and prescribes the downstream workflow ('show the amount to the end customer for confirmation before the write'). It also gives a selection rule among the mutually exclusive parameters.

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 no annotations present, the description carries the full burden and does so thoroughly. It discloses security behavior, handshake handling, deduplication, async processing, the manual BackOffice requirement, and the side effect of writing installation state unless record_state is false.

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 dense but every clause contributes meaningful behavioral or usage information. The main sentence front-loads the core purpose before listing details; it could be slightly more scannable, but it is not padded.

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 high-complexity scaffold tool with no annotations and no output schema, the description is unusually complete. It covers what is generated, how it behaves, the required manual procedure, and how it relates to sync_usage_rights, leaving the agent with a clear model of the tool's function.

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 are already well documented. The description adds a little context around record_state by restating the installation-state side effect, but it does not substantially enrich parameter understanding 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 opens with a specific verb and resource: 'Generates the HTTP endpoint that receives ProAbono notifications'. It then enumerates distinctive capabilities—signature verification, validation handshake, deduplication, out-of-band acknowledgement, and a worker—that clearly separate it from siblings like sync_usage_rights and generate_integration_code.

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 when this tool matters, especially the sentence tying it to sync_usage_rights and explaining that the BackOffice procedure is needed because 'no API can perform' it. It does not explicitly list exclusions or alternative tools, so it stops short of a 5.

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 no annotations, the description carries the burden. It states the tool returns matching documentation sections with their source file, implying a read-only, non-destructive operation. This is sufficient for a documentation search tool, though it doesn't explicitly declare read-only nature or side effects (which are absent).

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 wasted words. Purpose is front-loaded, usage guidance follows immediately, and return behavior is stated. Very efficient.

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 search tool with two parameters and no output schema, the description adequately covers what it does, when to use it, and what it returns (sections and source file). It doesn't mention limitations like maximum results, but the schema handles that. Complete enough 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?

Schema coverage is 100%, so parameters are already described. The description doesn't add extra semantics beyond the schema, just reiterates that 'question' is in plain language. Baseline 3 is appropriate given the 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 clearly states the tool answers natural-language questions about ProAbono integration from official installation documentation, listing specific topics (hosted pages, security hash, workflows, etc.). It distinguishes itself from sibling tools like get_api_reference by focusing on installation docs and natural-language queries.

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 instructs to use it before writing any integration code and to prefer it over recalling ProAbono behavior. This gives clear when-to-use guidance, though it doesn't explicitly name alternative tools for other scenarios (like using the API reference for exact endpoint details).

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 no annotations provided, the description carries the full disclosure burden. It clearly flags the operation as WRITE, states that it is a partial update affecting only the note, and explicitly notes that previously issued invoices are never modified. It omits details like error behavior or permissions, but the key side effects are disclosed.

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 tight sentences that front-load the operation type and core behavior, then add use cases and temporal scope. Every sentence earns its place with 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 two-parameter write tool with no output schema, the description covers what is changed, what is not changed, when it takes effect, and typical use cases. An agent has enough information to select and invoke 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 coverage is 100%, so the baseline is 3. The description adds useful semantics for the 'note' parameter by giving concrete examples of what belongs there, while the schema's own note description already explains the partial-update behavior. This goes just beyond the structured fields.

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 and resource: 'Sets the note printed at the bottom of every upcoming invoice of a ProAbono customer.' It also differentiates itself from sibling payment-settings tools by clarifying it 'changes nothing else about their payment settings.'

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 gives concrete intended uses (purchase order number, cost centre, customer accounting needs) and a clear temporal boundary: applies to future invoices only, never already issued ones. It does not explicitly name sibling alternatives like set_payment_method or set_next_billing_date, but the scope phrasing makes the appropriate use case clear.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the operation is a WRITE, guarantees no side effects on other payment settings, and explains the skip-versus-compress behavior for forward moves. It does not mention permissions or reversibility, but covers the most critical behavioral traits for a simple setter.

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, each earning its place: purpose+scope, use case, and prerequisite+behavior. The 'WRITE' prefix is a useful immediate signal, and the most critical information is front-loaded. 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 setter with full schema coverage and no output schema, the description is quite complete. It covers purpose, usage context, a key behavioral nuance, and a prerequisite. It omits edge cases like backward date moves or error conditions, but these are minor for this tool's simplicity.

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 both parameters (customer_ref and date_next_billing) are already documented with clear descriptions and an example. The description does not add extra semantic meaning to the parameters beyond what the schema provides, so a baseline of 3 is appropriate. The 'moving forward' hint is behavioral rather than 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 clearly states the verb ('sets'), the resource ('the date of the next billing of a ProAbono customer'), and explicitly scopes the action ('changes nothing else about their payment settings'). This distinguishes it from sibling set_* tools like set_invoice_note and set_payment_method by focusing on billing date only.

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 provides a concrete use case ('align a customer's billing on a date the merchant chose... common anniversary, or end of negotiated period') and an explicit prerequisite with an alternative tool: 'Read the current value with get_payment_settings first'. It also warns about a behavioral consequence ('moving the date forward skips a period rather than compressing it'), which guides correct usage.

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 no annotations, the description carries the behavioral disclosure burden. It clearly marks the operation as WRITE, notes that it changes nothing else about payment settings, and discloses that the endpoint refuses gateway-driven methods. It does not discuss overwrite/idempotency or error behavior, which are minor gaps for a simple two-parameter write.

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 front-loaded with 'WRITE' and the primary action, then adds exclusions and routing guidance. It is slightly redundant with the title's '(write)' and the schema's existing Card/DirectDebit exclusion, but every sentence carries useful selection and invocation 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 two-parameter tool with fully described schema and no output schema, the description is strong enough to select and invoke correctly. It would benefit from stating whether calling it again replaces an existing manual payment method and what a successful response looks like, but these do not block correct usage.

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 both parameters and their enum meanings. The description adds human-readable context ('bank transfer, cash, cheque or other') and reinforces the manual-only constraint, but does not materially expand on the schema's parameter 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 opens with a clear verb and resource: 'Records the manual payment method a ProAbono customer settles their invoices with.' It also distinguishes itself from sibling tools like get_payment_settings by framing this as a write operation that changes only the manual payment method, not other payment settings.

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 states when this tool applies: manual methods only (bank transfer, cash, cheque, other). It also gives a concrete exclusion and alternative: Card and DirectDebit are refused, and card setup should go through the Customer Portal, 'never through this tool.' This removes ambiguity about when to choose 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?

With no annotations, the description carries the full burden. It discloses the write nature ('WRITE') and explains the effect: it grants rights and transitions a draft or suspended subscription to active. It also notes that rights only exist after starting, which is a valuable behavioral nuance. It does not cover side effects like billing when bill_now is true, but that is parameter-specific, not core 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 efficient and front-loaded with 'WRITE'. Every sentence adds value: the purpose, the state transition, the lack of an alternative, and the follow-up action. It is slightly longer than necessary but each part 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 write tool with no output schema, the description covers the main use case and post-condition (rights granted, re-read with get_usages). It does not discuss errors or prerequisites, but those are not critical for correct invocation. The core behavior is sufficiently explained.

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 explains all three parameters. The description does not add any parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies. It mentions the overall purpose but not parameter interactions.

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 ('activates'/'restarts') and resource ('subscription'), and clearly differentiates from siblings like suspend_subscription and create_subscription by explaining the same transition covers draft and suspended states. It also clarifies there is no separate resume operation, making it unambiguous.

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 identifies this as the tool to unsuspend a subscription and notes there is no alternative operation ('no separate resume or unsuspend operation'). It also implies when to use it (draft or suspended states) and suggests a follow-up action with get_usages, giving clear selection 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?

No annotations are provided, so the description carries the behavioral burden. It clearly discloses that this is a WRITE operation, that a suspended subscription stops granting rights and stops being billed, that it is not terminated, and that get_usages should be re-read afterward. Missing specifics like permissions or response shape prevent a 5.

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 tight sentences front-load the WRITE nature and core behavior. Every sentence adds value: what suspension means, how it differs from termination, and what to do afterward.

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 one-parameter mutation with no output schema and no annotations, the description covers the operation, its behavioral effects, sibling distinctions, and a follow-up action. It does not describe the response payload or authorization requirements, but these are not essential for selecting and invoking 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?

Schema description coverage is 100%, and the input schema already documents subscription_id as the internal identifier from list_subscriptions. The tool description adds no parameter-level semantics beyond the schema, so the baseline of 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 uses a specific verb and resource: 'Suspends a ProAbono subscription.' It also distinguishes the operation from terminate_subscription and connects it to start_subscription, so an agent can tell it apart from sibling subscription tools without opening their 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?

The description names the two closest alternatives, start_subscription and terminate_subscription, and explains the key distinction: suspension is reversible and not a termination. It stops short of an explicit rule like 'use terminate_subscription for permanent cancellation,' but the routing is strongly implied.

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 no annotations, the description carries the full burden and it does substantial work: it discloses that the tool reads the account's real Features, reads a customer's Usages when customer_ref is given, returns generated code rather than modifying the app directly, and includes a confirmation step for billable write-backs. It could mention side effects such as writing installation.json or auth requirements in the description itself, but the schema's record_state parameter covers the filesystem touch.

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 front-loaded with the core purpose and every clause adds information; it is a dense but efficient paragraph. It is longer than strictly necessary and could benefit from structure, but 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?

For a code-generation tool with 5 parameters, no annotations, and no output schema, the description is thorough: it explains what the returned code contains, the inputs that affect generation, the diagnostic use case, and an explicit semantic exclusion. It is not exhaustive — prerequisites and integration points of the generated code are implied rather than stated — but it is genuinely complete 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 description coverage is 100%, so the baseline is 3. The description adds some meaning beyond the schema — the diagnostic rationale for customer_ref ('how an empty response is told apart from a broken integration') and the semantic rule that rights come from the Usage API, not the offer. This is helpful but not a heavy compensation for gaps since the schema already documents each parameter well.

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 a specific verb and resource ('Generates the code that reads a customer's rights from the ProAbono Usage API') and enumerates exactly what it returns: rights module, gate at a call site, write-back, and cache expiry policy. The 'step 3 of the In-Site installation' positioning plus the 'Never gate on the offer reference' exclusion distinguish it from siblings like get_usages, generate_pricing_table, and generate_integration_code.

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?

Places the tool clearly within the In-Site installation sequence ('step 3... the one that decides what a signed-in user may actually do') and explains when to pass customer_ref for diagnosing empty responses. It gives a strong when-not for the code it produces ('Never gate on the offer reference') but does not explicitly name alternative tools to choose instead, falling just short of a 5.

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?

Since no annotations are provided, the description carries the full burden. It discloses the key behavioral nuance: by default termination is not immediate but takes effect at the end of the current term, and that the subscription cannot be restarted after termination. This is critical for correct usage and is clearly stated.

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 concise yet rich, packing critical behavioral details into three sentences. It front-loads the key fact (WRITE) and default behavior, then provides parameter guidance and a warning. Every sentence earns its place with 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?

For a write operation with no output schema and no annotations, this description covers all necessary aspects: what the tool does, when to use it, behavioral nuances, parameter semantics, and cautions. An agent has everything needed to call it correctly and avoid misuse.

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 all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful context by explaining the effect of each parameter (immediate vs. termination_date vs. default) and their implications (e.g., immediate ends now, termination_date overrides term end). This adds value 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 verb ('Terminates'), resource ('ProAbono subscription'), and the fact that this is a write operation. It also distinguishes itself from sibling tools (suspend_subscription and its reversibility), making it easy for an agent to select the right tool.

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 says when to use this tool (to terminate, with options for immediate, scheduled, or end-of-term), and when not to: 'suspend_subscription is the reversible one' for cases needing reversibility. It also warns against the common mistake of revoking access immediately, providing clear usage context.

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 no annotations, the description carries the behavioral burden. It does disclose the write nature ('WRITE'), partial update behavior, and a meaningful caution about using the customer's own address/tax data. However, it omits other mutation-relevant details such as permissions, idempotency, or validation 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 with 'WRITE.' Each sentence adds meaningful context, and there is no redundant filler. It could briefly mention a sibling alternative, but overall it is efficiently structured.

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?

This is a mutation tool with 12 parameters, no annotations, and no output schema, yet the description covers only the core update behavior and one caution. It leaves parameter semantics, alternative tool selection, and side effects under-specified for an agent needing to invoke 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 only 33%, and the description does not compensate by explaining the remaining parameters. It adds some context around tax_information ('VAT treatment is derived from') but does not clarify fields like address_line1, address_line2, or customer_ref 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 clearly states a verb and resource: 'Updates the billing address of a ProAbono customer.' This is unambiguous and distinct from the general customer update tool by name and title. It does not explicitly compare itself to sibling update_customer, so it stops short of a top score.

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 gives no when-to-use guidance or alternative routing. The 'Only the fields passed are changed' sentence explains partial-update behavior, not when to choose this tool over update_customer. Sibling naming alone is not sufficient 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?

With no annotations, the description carries full burden. It explicitly marks the operation as 'WRITE', discloses that it terminates the current subscription and creates a new one, that the returned identifier is new, and that customer rights change (advising to re-read usages and stop using the old identifier). It also explains the default end-of-term timing and the immediate override. This is comprehensive behavioral 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?

The description is three sentences, tightly packed with essential information. It front-loads the 'WRITE' marker and then explains the core behavior, side effects, and timing. There is no fluff or redundant phrasing; every sentence 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 complex write operation with no output schema, the description covers the essential behavioral context: side effects, identifier change, rights change, and timing. It omits edge cases like failure scenarios or engagement bypass details, but those are partly covered by the parameter schema. Overall, it is complete enough for an agent to call the tool correctly without further clarification.

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 provides 100% coverage for all five parameters, each with its own description. The tool description adds minimal parameter-level information beyond what the schema already states—it reinforces the behavior of 'immediate' but does not introduce new semantics for 'bill_now' or 'ignore_engagement'. Since the schema does the heavy lifting, a baseline of 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 verb ('Moves') and resource ('a ProAbono subscription to another offer'), and clarifies that upgrade and downgrade are the same operation. This clearly distinguishes it from sibling tools like terminate_subscription or create_subscription, which have different intents.

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 explains what the operation does but does not explicitly guide the agent on when to choose it over alternatives like terminate_subscription or create_subscription. It implies usage for changing offers, but there is no explicit 'use this when' or 'do not use when' context. The default timing behavior is noted, but not tool selection.

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 no annotations, the description carries the full burden and does so thoroughly. It declares 'WRITE' up front, explains that steps 2 and 3 are exercised against the real account, details the exact upsert behavior on customer_ref (created if missing, left unchanged if existing, generated mcp-verify- reference otherwise), describes static file checks against go-live rules, and explicitly reports unverifiable items as pending instead of pretending.

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 long but appropriately detailed for a complex verification tool with many checks. It is front-loaded with 'WRITE' and the core purpose, and each sentence describes a distinct behavior or check, though the density is high and could be slightly more scannable.

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 complexity, lack of annotations, and absence of an output schema, the description is complete enough. It covers the write side effect, the execution scope, the static checks, the unverifiable items reported as pending, and the final twelve-item checklist, leaving no major gaps 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?

Schema description coverage is 100%, so the schema already documents all three parameters in detail. The description adds context around the customer_ref upsert and offer_ref's effect on the insite-subscribe query, but most of this is duplicative rather than supplementary, so the baseline of 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 verb (verify/checks) and resource (In-Site installation before shipping), and distinguishes itself from installation tools by describing a verification-and-checklist role. However, it does not name or contrast with siblings such as installation_status or install_insite, so sibling differentiation is implied rather than explicit.

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 gives a clear usage condition: 'Run it before shipping, not after.' This tells the agent when to invoke the tool. It does not name alternatives or when-not-to-use, but the context is unambiguous for a pre-ship verification step.

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