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

With no annotations, the description carries the full burden and discloses key behaviors: WRITE, terminate is not immediate by default, upgrade terminates the current subscription and creates a new one, and customer rights change. It does not mention permissions or rate limits, but the side-effect disclosure is strong.

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, first word signals write, then the core purpose, then critical caveats. 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 complex 5-parameter mutation tool with no output schema and no annotations, the description covers the main behaviors, side effects, and follow-up actions. It does not detail the 'start' or 'suspend' behavior in depth, but the schema and enum fill some gaps, so it is slightly above adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and every parameter already has a description. The text adds some meaning (immediate affects terminate, offer_ref is for upgrade, subscription_id comes from list_subscriptions), but this is modest value beyond the schema, matching the 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 clearly states a specific verb ('Moves') and resource ('an existing ProAbono subscription'), then enumerates the exact actions (upgrade, downgrade, start, suspend, terminate). It differentiates from siblings like create_subscription by specifying 'existing' and from list_subscriptions by being a write operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives practical guidance: identify the subscription via list_subscriptions, and read customer rights with get_usages after an upgrade. It implies this tool is for existing subscriptions, but does not explicitly say when to prefer create_subscription or list the exclusions, 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 must carry behavioral disclosure. It clearly marks the operation as a write and explains the upsert semantics, which is critical behavior. However, it doesn't address authorization requirements, reversibility, or what happens to existing fields on update, 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 efficiently structured, starting with a 'WRITE.' marker, then the core purpose, then the upsert detail, then the recommendation. Every sentence adds value and the key information is front-loaded. It is a bit longer than minimal but remains focused.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 5 parameters, no output schema, and no annotations, the description covers the essential context: the upsert nature, the recommended usage timing, and the dependency on hosted pages. It doesn't describe the return value, but that's often not needed for calling. The description plus schema is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with all parameters already described in the schema. The description adds context about the customer_ref being derived from the application's user identifier (already in schema) and mentions the Segment, but doesn't enhance parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Creates'), resource ('ProAbono customer'), and context ('in the configured Segment, keyed by the reference'). It also distinguishes itself from update_customer by explicitly noting the upsert behavior, making the tool's role clear even without inspecting 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?

It provides a clear recommendation for when to use the tool ('at sign-up or first login') and explains why (hosted pages and rights read need the customer). It implies this is the primary write path by describing the upsert behavior, though it doesn't explicitly name alternatives like update_customer.

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 disclosure burden and does more than a generic 'creates' line: it flags WRITE, explains that the subscription is a copy of the offer, and defines the Draft vs. active distinction via start_now. The 'pass an override' phrase is not represented in the schema, which slightly muddies the behavioral contract, but the core side effects are clearly conveyed.

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 front-load the WRITE marker and the core action before adding usage context and state semantics. The 'override' sentence is a little vague and refers to a capability not visible in the schema, so the structure is strong but not perfectly 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?

The description covers the key workflow distinction and the Draft/active semantics, which is helpful for a creation tool with no annotations. However, with seven parameters and no output schema, it omits return values, error conditions, and prerequisites beyond 'existing customer', leaving an agent to infer several call-time details.

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 input schema already documents every parameter; the description adds marginal value by explaining that customer_ref refers to an existing customer and that start_now activates the subscription immediately. It does not enrich the semantics of bill_now, metadata, ensure_billable, or buyer_customer_ref, matching the baseline for full 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 the unambiguous verb 'Creates' and identifies the exact resource ('a ProAbono subscription linking an existing customer to an offer'). It also distinguishes itself from the hosted subscription workflow, so an agent can separate this API-based creation from the customer self-service 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?

It explicitly says this is the API path and that a customer choosing a plan themselves should go through the hosted subscription workflow, providing a clear exclusion. It does not, however, spell out when to use this instead of change_subscription or list_subscriptions, leaving some routing 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 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?

With no annotations, the description carries the full behavioral burden. It describes the returned contract and implies a read-only lookup, but it does not explicitly state that the tool has no side effects or require any authentication context. This is adequate for a reference lookup but leaves some behavioral assumptions implicit.

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 focused sentences: the first states what the tool returns, the second states when to use it. Every phrase earns its place, 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?

The description explains the return value at a high level and gives usage context, which is useful given there is no output schema. However, both parameters are optional in the schema and the description does not clarify that at least one of object or endpoint is needed, nor what happens when both are supplied.

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 input schema already documents both parameters. The description adds examples like Customer, Subscription, Offer, Feature or Usage, but these are illustrative rather than essential to understanding the 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 states a specific verb ('Returns') and resource ('the exact contract of a ProAbono Live API endpoint... or of a named object'), with concrete examples like Customer and Subscription. This clearly distinguishes it from the action-oriented sibling tools such as create_customer or list_subscriptions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says to use this tool 'before calling or generating a call to the ProAbono API,' giving a clear intended context. It does not name alternatives or exclusions, but the guidance is specific enough for an agent to know when to reach for 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?

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 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, 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 and handles it well. It discloses Read-only behavior, result granularity ('one entry per Feature'), the 'as ProAbono sees it' interpretive lens, and the important ambiguity of empty results.

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, front-loaded with the core action, and every sentence adds value: purpose, semantics, and ambiguity handling. The em-dash aside is efficient rather than bloated.

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 what the result means, how to interpret edge cases, and when to use an alternative. Nothing essential is missing 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 description coverage is 100%, so the schema already documents both parameters. The description does not add specific parameter-level guidance beyond what the schema provides, which meets the baseline for full 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 uses a specific verb and resource ('Reads a customer's Usages') and clarifies the concept as 'what that customer may do right now, as ProAbono sees it.' It clearly differentiates from siblings like list_subscriptions and get_offer by emphasizing that this is the authoritative source for gating access.

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 the tool is the right choice ('This is the source an application gates access on -- never the offer reference') and provides an alternative instruction for an ambiguous empty result: check list_subscriptions. This is direct, actionable 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 burden and does well: it clarifies the tool generates code rather than performing the installation, lists the returned artifacts, and discloses the authentication requirement. It could add more about side effects or failure conditions, but the core 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?

Four sentences, each carrying distinct value: purpose, installation step, return artifacts, and authentication constraint. There is no filler or repetition, and the most important orientation 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 tool with no output schema, the description gives a solid high-level picture of what is returned and the prerequisite condition. It could be more complete by hinting at what follows step 1 or describing the returned snippet format, but nothing essential is missing for calling the 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 description coverage is 100%, so the schema already documents all three parameters. The description adds installation context but does not enrich parameter meaning beyond the schema, matching the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Generates the code that embeds the ProAbono Customer Portal inside a page'), names the customer-facing content covered, and distinguishes this from sibling code-generation tools by calling out 'This is step 1 of the In-Site installation'. An agent can tell what this tool produces and how it relates to the installation flow.

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 clear context for when to use it: it is the first step of the In-Site installation and requires an authenticated customer area. It does not explicitly name alternatives or say when not to use it, so it stops short of a 5, but the context is strong enough to guide 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?

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 provided, the description carries full behavioral burden. It discloses that the tool is read-only, reads every page ('Reads every page, not just the first'), and returns offers with features and pricing. This is meaningful beyond the schema, though it omits edge-case or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four focused sentences, front-loaded with the core action and resource, followed by use cases and behavioral notes. Every sentence adds value; there is no redundancy 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?

The description covers the primary purpose, explicit use cases, read-only nature, pagination behavior, and return contents. It lacks explicit alternative routing and edge-case details, but for a straightforward list tool with complete schema documentation, it is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (customer_ref, visible_only) have clear schema descriptions. The tool description does not add parameter-level meaning beyond what the schema already provides, so 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?

The description states a specific verb and resource: 'Lists the ProAbono offers the configured Segment exposes'. It also specifies what is included ('Features each one carries and its pricing'), clearly distinguishing this list tool from siblings like get_offer (single offer) and list_features (features 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?

Provides explicit use cases: 'Use it to show a catalogue, to pick the offer a subscription or a pricing table targets, or to check the prerequisite that at least one offer exists and carries at least one Feature.' It does not explicitly say when not to use it or name alternatives, but the context is clear enough for a competent 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?

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 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, 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 behavioral disclosure. It explicitly says 'WRITE', explains the upsert side effect, states that only passed fields are modified, and warns about overwriting values the customer may have set through hosted pages. This is unusually transparent for a mutation 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 concise and front-loaded with 'WRITE' and the core action. Each sentence contributes necessary information: identification, upsert behavior, partial update semantics, and a caution about field ownership. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write tool with no annotations and no output schema, the description covers the key invocation concerns: what it does, when it creates, how updates behave, and which fields should be avoided. It is slightly incomplete only in that it does not describe the response shape or error behavior, but the 100% schema coverage and detailed behavioral warnings make it 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter-level guidance beyond the schema: it clarifies that customer_ref is the shared reference, that fields are only changed when passed, and that name/language should not be passed if the merchant is not the authority. This goes beyond the simple 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 states the specific action ('Updates a ProAbono customer'), identifies the resource ('customer'), and clarifies the unique identification mechanism ('shared reference'). The upsert behavior also distinguishes it from a plain create, so the agent can tell it apart from create_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?

It provides clear context: customers are updated by shared reference, unmatched references trigger creation, and only passed fields are changed. It also gives a strong 'do not pass' warning about name and language fields being overwritten. It does not explicitly name sibling tools as alternatives, but the context is clear enough.

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