ChargeOver MCP by usefulapi

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

With annotations already declaring readOnlyHint=false, idempotentHint=false and destructiveHint=true, the description still adds real behavioral value: 'No email is sent by this call' discloses a side effect the annotations don't cover, and 'Returns the new user_id' plus 'POST /user' describe the mechanism and result. It does not, however, explain the destructive/auth implications the destructiveHint annotation implies.

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

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

Four short, front-loaded fragments with zero filler: the write scope, the side-effect disclaimer, the return value, and the endpoint. 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 nine-parameter write tool with no output schema, the description usefully covers the return value ('new user_id') and the no-email side effect, and the annotations handle the safety profile. It could say more about required permissions or the required customer_id, 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 description coverage is 100%, with all nine parameters documented in the schema itself (including the name vs first_name/last_name alternative). The description adds no parameter-level detail beyond that, so the baseline 3 applies when the schema carries the load.

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

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

States a specific verb and resource ('add a contact (person) to an existing customer'), disambiguating from the sibling create_customer by clarifying that this creates a person, not a customer. An agent can distinguish it from chargeover_create_customer or chargeover_create_note 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?

The phrase 'to an existing customer' implies the prerequisite that the customer must already exist, and the 'WRITE:' prefix signals its place among read siblings. However, it names no alternative tools and gives no explicit when-to-use/when-not guidance, so usage is only 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?

Annotations already declare readOnly=false, idempotent=false, destructive=true, so the write nature is covered. The description adds genuinely new behavioral context: explicit absence of side effects (no charge/invoice/email), the returned customer_id, and the external_key uniqueness constraint — all beyond the annotations.

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

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

Front-loaded with 'WRITE:' and packed into a few high-signal clauses with zero filler. Side-effect exclusions, return value, uniqueness, and the sibling call are all stated tersely.

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 19-param mutation with no output schema, the description covers the missing return value (customer_id), the safety-relevant side-effect profile, and the de-duplication prerequisite. Nothing an agent needs to invoke it correctly is absent.

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 earns above baseline by explaining that the superuser_* fields collectively add a primary contact (grouping intent the schema lists individually) and by flagging external_key as a unique, non-reusable key.

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 ('create a new customer') and leads with a 'WRITE:' marker. The parenthetical scope note and the reference to chargeover_list_customers / chargeover_update_customer siblings make it unambiguous which tool to pick.

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 prerequisite ('Use chargeover_list_customers first to avoid a duplicate') and clarifies what this call does NOT do (no charge, invoice, or email). It stops short of stating when to prefer create vs update_customer, but the de-duplication guidance is concrete.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, so the safety profile is covered. The description adds real value beyond them: the note is internal-only (never sent to the customer), it returns the note id, and it hits POST /note. It does not explain the destructiveHint=true side effect 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?

Three tightly packed sentences, front-loaded with the WRITE signal, then scope, then behavioral clarification, then return and endpoint. 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?

No output schema exists, but the description states the return value (note id), and the schema covers all required params and the enum. Only edge cases (record not found, max length enforcement) are unaddressed, which is minor for a simple write 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 including the enum and the billing_package/user aliases. The description largely restates those same record types, adding only the human-readable mapping (subscription, contact), which is the baseline 3 case.

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 (add a note) and resource, and enumerates exactly which record types it attaches to, which cleanly separates it from chargeover_list_notes and the create_* siblings. The 'WRITE:' prefix and endpoint make the operation 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?

Implied usage is clear (attach an internal note to an existing record), and the parenthetical clarifies the note is team-visible and never customer-facing. However, it names no alternatives and gives no when-not-to-use guidance (e.g., versus chargeover_list_notes or update tools), so routing must be inferred.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, so safety is largely covered. The description adds genuinely new behavior: nothing is billed, no email is sent, the quote stays open until sent/accepted, and the call returns quote_id. It does not restate idempotency or permission requirements, so it is strong but not exhaustive.

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 a 'WRITE:' marker, then behavior, then parameter semantics, then return value and endpoint. The paycycle expansion is long but it is the only part that could not be inferred elsewhere, and every sentence carries 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?

No output schema exists, and the description compensates by naming the return value (quote_id) and the underlying endpoint (POST /quote). Required inputs, side effects, and preconditions are all covered, leaving nothing an agent needs missing 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?

With 100% schema coverage the baseline would be 3, but the description decodes the paycycle enum ('mon = monthly, 2mn = every 2 months, ...'), which the schema exposes only as opaque codes with the label 'Billing cycle of the quote.' It also clarifies the semantic constraint that each line's item must pre-exist. This is real meaning 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?

States a specific verb and resource ('WRITE: create a quote (a proposal)') and scopes it to 'an existing customer,' which routes the agent away from chargeover_create_customer/contact. The parenthetical gloss on 'quote' removes ambiguity about what is being produced. An agent can distinguish this from every sibling create_* tool 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 clear context: the customer must already exist, and each line must reference an existing item, with an explicit pointer to chargeover_list_items for that lookup. It does not state when NOT to use this (e.g. versus creating a subscription/invoice), so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds the shape of the returned record (name, email, phone, username, parent customers), which matters because there is no output schema, but it says nothing about error behavior for a missing id or rate limits.

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?

One tight sentence that front-loads the action and scope, then lists returned fields. The trailing 'GET /user/{user_id}' endpoint is marginally useful for debugging but borders on 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 one-parameter read tool with annotations covering safety, this is largely complete, and enumerating return fields substitutes for the absent output schema. Minor gaps remain around not-found behavior, which an agent might reasonably want to know.

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 single parameter is fully documented in the schema. The description's 'by user_id' restates the schema's 'The user_id (a number)' without adding format, range, or lookup-failure semantics, so the 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?

The description gives a specific verb ('Get one contact') and resource, and the qualifier 'one' separates it from the sibling chargeover_list_contacts. It also clarifies that a 'contact' is a 'user', which resolves naming ambiguity. It falls short of 5 only because the sibling it contrasts with is not named explicitly.

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

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

There is no statement of when to use this tool versus chargeover_list_contacts or chargeover_get_customer, nor any prerequisites. The single-record scope implies lookup-by-id usage, but nothing is spelled out.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond the annotations by enumerating the categories of data returned (addresses, contacts, terms, balance, custom fields) and citing the underlying endpoint, which is meaningful for a tool with no output schema. It does not mention error/not-found behavior, keeping 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?

A single front-loaded sentence plus an endpoint citation, with zero filler. The resource and key returned fields come first, and the HTTP path is compact trailing context.

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 read tool with readOnlyHint annotations, the description covers the essentials, and its field enumeration partially compensates for the absence of an output schema. It stops short of describing pagination/expansion or failure modes, but nothing critical for correct invocation 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% (the 'id' parameter is documented as the numeric customer_id), so the schema carries the parameter burden. The description's 'by customer_id' matches and mildly reinforces the schema but adds no format, range, or lookup-detail beyond it, making the baseline 3 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?

States a specific verb and resource ('Get one customer by customer_id') and enumerates the fields returned (company, status, addresses, contact, terms, balance, custom fields), which clearly separates it from list_customers and the other get_* siblings. The endpoint notation 'GET /customer/{customer_id}' reinforces the single-record 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?

Usage is implied by 'one customer by customer_id', so an agent can infer this is the single-record lookup versus chargeover_list_customers. However, no explicit when-to-use, prerequisites, or named alternative is given, so guidance remains inferential rather than stated.

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

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

The readOnlyHint=true annotation already establishes the safe read profile, so the description only needs to add context. It does add value by enumerating what the response contains and citing the underlying endpoint, but it says nothing about failure behavior (e.g. what happens for a nonexistent id) or authorization scope.

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?

A single front-loaded sentence with a useful field list and no filler. The trailing 'GET /invoice/{invoice_id}' endpoint restates the tool name and the id parameter, so it is largely redundant rather than harmful.

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 correctly compensates by naming the main components of the returned invoice, which is the key completeness gap for a get tool. It is nearly complete, missing only error/not-found behavior and any auth or rate-limit context.

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

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

There is exactly one parameter and schema coverage is 100% ('The invoice_id (a number).'), so the schema already fully documents it. The description's 'by invoice_id' adds no semantics beyond the schema, and the baseline of 3 is appropriate when the schema does the heavy lifting.

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 ('Get one invoice by invoice_id') and enumerates the fields returned (status, line items, totals, balance, payments/credits, billing address), which makes the scope concrete. It distinguishes itself from the large family of list_* siblings implicitly via 'one invoice', but never names an alternative, so it stops short of full sibling differentiation.

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?

Usage is only implied: an agent can infer this is the single-entity variant of chargeover_list_invoices and should be used when an invoice id is known. There is no explicit when-to-use, when-not-to-use, or named alternative, which matters here given how many similarly shaped get_* / list_* siblings exist.

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?

readOnlyHint=true already covers the safety profile, so the bar is lower. The description goes beyond the annotation by disclosing the response contents (name, type, SKU, pricing tiers per currency) and the underlying endpoint GET /item/{item_id}, which is genuinely useful given there is no output schema. It stops short of mentioning auth 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?

A single compact sentence that front-loads the action and the keying parameter, then enumerates the notable return fields and the endpoint. Every clause earns its place with no redundant padding.

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, read-only lookup with full schema coverage and no output schema, the description supplies the return-field summary an agent would otherwise lack. What remains missing is minimal, such as error handling for a nonexistent item_id.

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?

With 100% schema description coverage on a single parameter, the schema already defines 'id' as the item_id with type and bounds. The description restates the parameter name and the path placeholder but adds no syntax or format detail beyond the schema, so 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 a specific verb and resource ('Get one item... by item_id') and helpfully disambiguates what an 'item' is (product, service or discount). The singular framing implicitly separates it from chargeover_list_items, but no sibling is named explicitly, so it falls just 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?

Usage is implied by the shape of the tool: fetch a single item when you already hold its item_id. There is no explicit statement of when to prefer this over chargeover_list_items, nor any prerequisite listed, so guidance remains inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine behavioral value by disclosing what the response contains (status, line items, totals, memo, and links to the resulting invoice or subscription), which tells the agent about the data shape after the read.

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?

One tightly packed sentence front-loads the operation and the identifier, then lists the returned fields, followed by the endpoint. No sentence is wasted and nothing needing emphasis is buried.

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 helpfully enumerates the returned fields, which is the main thing an agent would otherwise lack. For a single-parameter read tool with readOnlyHint and full schema coverage, this is nearly complete; only an explicit pointer to list_quotes for browsing 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% and the single parameter carries its own description ('The quote_id (a number)'), so the schema does the heavy lifting. The description's 'by quote_id' merely restates the parameter without adding format or constraint detail, making the baseline 3 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?

States a specific verb and resource ('Get one quote by quote_id') and enumerates the returned content (status, line items, totals, memo, links), which cleanly distinguishes it from the sibling list_quotes and create_quote. An agent can identify the operation and its scope 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?

The phrase 'by quote_id' implies the retrieval condition and the GET endpoint confirms a read by identifier, but there is no explicit when-to-use or when-not-to-use statement and no named alternative such as list_quotes for browsing. Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint=true, so the safe read-only nature is known. The description adds the endpoint (GET /_report/{report_id}) and the shape of the returned definition, but does not disclose auth needs, rate limits, error behavior, or other operational traits beyond what the annotation implies.

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

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

Three short sentences with zero waste: the return fields are front-loaded, the usage guidance follows, and the endpoint is last. 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?

Given a simple one-parameter read with no output schema, the description supplies the returned definition fields and the key usage rule. 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?

Schema coverage is 100%: the single report_id parameter is fully documented as coming from chargeover_list_reports. The description adds no parameter syntax or meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description identifies the resource (a report's definition) and lists the specific fields it returns (name, available_filters, available_columns, default_columns). It distinguishes itself from chargeover_run_report by telling the agent to read it first. The only minor gap is the lack of an explicit verb in the description itself, though the title and tool name supply 'Get'.

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 directs the agent to read this before chargeover_run_report to know which filters and columns to use. This names the alternative tool and the condition that selects it, leaving no inference required.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully names the fields returned and the underlying endpoint, but adds nothing about auth, error behavior for a missing package_id, or any rate limits.

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?

Single front-loaded sentence covering resource, key, return fields, and endpoint, with no redundant text. Every clause carries 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 compensates by enumerating the return contents (status, cycle, pay method, next invoice date, line items). For a simple single-resource read this is nearly sufficient; only error/not-found behavior is unaddressed.

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 'id' parameter is fully documented as the package_id. The description repeats that mapping ('by package_id') without adding format, bounds, or lookup guidance 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?

States a specific verb and resource ('Get one subscription (package) by package_id') and enumerates the salient returned fields, so an agent can distinguish it from chargeover_list_subscriptions at a glance. The endpoint 'GET /package/{package_id}' reinforces the single-resource 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 phrase 'Get one subscription ... by package_id' implies usage, but the description never states when to use this versus chargeover_list_subscriptions or other get_* siblings, nor any prerequisites. Usage is inferable but not prescribed.

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

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

The readOnlyHint annotation already establishes this as a safe read, so the description isn't carrying the safety burden. It does add domain context beyond the annotation: only completed transactions are returned ('already happened'), and it discloses the endpoint (GET /transaction/{id}). No pagination, rate-limit, auth, or not-found behavior is described, which keeps this at a solid but not rich 3.

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?

A single dense sentence with the operation and key qualifiers front-loaded, followed by the endpoint. Nothing is padded, though the field enumeration is a long inline list that could be trimmed.

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?

There is no output schema, so the description usefully enumerates the returned fields (amount, method, status, applied invoices, related refunds), which is exactly what an agent needs to know before calling. The remaining gap is the absence of any failure-mode or filtering context, but for a single-ID read tool this is close to 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% – the 'id' parameter is documented in the schema as the transaction_id with type and bounds. The description's 'by transaction_id' adds no syntax, format, or sourcing detail beyond that, so the 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 a specific verb ('Get one transaction') and resource, and disambiguates the domain term by defining a transaction as 'payment, refund or credit that already happened'. It also enumerates the fields returned. It does not name its nearest sibling (chargeover_list_transactions), though the singular 'one' vs. list distinction is reasonably clear from the name.

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?

Usage is implied by 'by transaction_id' – the agent infers this is the lookup path when a specific transaction ID is known. There is no explicit when-to-use guidance, no mention of when to prefer chargeover_list_transactions, and no stated prerequisites or error conditions.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest and does: it discloses the paging mechanism (pass next_offset as offset), the filterable surface, and the HTTP verb/path. It does not mention auth requirements or rate limits, but for a safe read list it adds genuine operational context beyond the annotation.

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 tightly packed sentences, front-loaded with purpose, then filters, then paging, then endpoint. No filler and no repetition of schema-level defaults.

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 four-parameter list tool with no output schema, the description covers the filtering surface, pagination, and endpoint. The remaining gap is return shape, but next_offset implicitly signals the paged-envelope format, so an agent has enough 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 baseline is 3, but the schema itself defers to the description for the valid filter field names ('the list tool's description names the valid ones'). The description supplies that exact list, making it materially additive rather than redundant.

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 ('List contacts') and immediately resolves a naming ambiguity that would otherwise confuse an agent: 'the people at customers; the API calls them users.' It also names the backing endpoint (GET /user), so the tool is unambiguously distinct from get_contact and the create/update 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?

Gives concrete usage context: which fields may be filtered, how to page via next_offset, and the parenthetical 'contacts of one customer' for customers.customer_id. It stops short of stating when to prefer get_contact or how to combine filters with other list tools, so it is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds real behavioral context by disclosing the returned fields, pagination behavior, and the underlying GET /coupon call. It doesn't cover rate limits or default page size behavior beyond what the schema states.

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?

Compact and front-loaded, with the resource and returned fields leading. The phrase 'Filterable fields: none documented' is slightly awkward but earns its place by heading off filter attempts.

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-only list tool with no output schema, the description is reasonably complete: it names returned fields and explains pagination. It could say more about the default page size interplay, but nothing essential for a correct 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?

Schema description coverage is 100%, so limit, order, offset, and filters are already fully documented. The description adds only the pagination hint ('pass next_offset as offset'), which is marginal and slightly at odds with the schema's naming. Baseline 3 applies when the schema does the heavy lifting.

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 (List) and resource (coupons), and enumerates the returned fields (code, description, type, enabled, linked discount item), which clearly differentiates it from list_contacts, list_invoices, etc. It stops short of explicitly contrasting with siblings, but the resource is 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?

It establishes when filtering is not useful ('Filterable fields: none documented; the list is small') and how to page, which is genuine usage context, but gives no explicit when-to-use/when-not guidance or alternative tools. Adequate but with clear gaps.

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

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

Annotations already carry readOnlyHint=true, so the safety profile is covered; the description adds real behavioral detail beyond that, including the pagination contract (next_offset from the previous reply) and code semantics for customer_status_state/customer_status_str. It does not mention rate limits, default page size, or whether results are sorted by default.

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?

Purpose is front-loaded, followed by the filter vocabulary, then the pagination rule and endpoint. The single run-on filter sentence is dense but every element is useful; 'GET /customer' is borderline filler for an agent that only needs arguments.

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 readOnlyHint set and no output schema, the description needs to cover invocation, filtering and paging — and it does. It omits how the response is shaped (aside from the next_offset convention) and gives no example of a combined filter, but nothing required to call the tool 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?

Schema coverage is 100% for limit/order/offset/filters, but the schema explicitly defers filter field names to the tool description ('the list tool's description names the valid ones'), and the description delivers that list including custom_1..custom_50 and decoded status codes. This is load-bearing information the agent cannot get from the schema alone, so it exceeds the baseline 3.

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

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

The description opens with a specific verb+resource ('List customers') and even defines the entity ('companies that are billed'), which immediately separates it from chargeover_get_customer, chargeover_create_customer and chargeover_update_customer. It stops short of explicitly naming a sibling or stating the search-vs-fetch distinction, so it is clear but not sibling-routed.

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?

Usage is only implied: enumerating filterable fields signals that this doubles as a search tool, and 'Paged: pass next_offset as offset' gives a concrete operational instruction for continuing a result set. There is no explicit when-to-use/when-not statement and no guidance on choosing this over chargeover_get_customer for a single record.

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

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

Annotations only declare readOnlyHint=true, so the description adds real value by disclosing pagination behavior ('Paged: pass next_offset as offset') and the endpoint (GET /invoice). It does not cover auth, rate limits, or result-size implications beyond mentioning fields, so it stops short of 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-loads purpose and returned data before the filter enumeration, paging note, and endpoint. The filter field list is long but necessary because the schema depends on it; a bulleted format would be cleaner but every element 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?

No output schema exists, and the description compensates by naming the fields returned (status, totals, credits, payments, balance) and explaining pagination. It omits auth requirements and paging edge cases, but is largely complete for a 5-param list 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%, so baseline is 3, but the description is the sole source of valid filter field names (the schema explicitly defers to 'the list tool's description names the valid ones'). It also clarifies the offset parameter via next_offset, adding 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?

States a specific verb+resource ('List invoices') and enriches it with the returned data shape ('status, totals, credits, payments and balance'). The plural 'List' clearly distinguishes it from the sibling get_invoice 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?

Implies usage as the invoice listing tool but gives no explicit when-to-use vs get_invoice or other list tools, and no exclusions or prerequisites. The paging note ('pass next_offset as offset') is a helpful operational instruction, but routing guidance is absent.

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?

readOnlyHint=true already declares the safety profile. The description adds that results are paged and that next_offset is passed as offset, plus the underlying GET /item endpoint, but the pagination detail largely duplicates the offset parameter's own schema text, so the added behavioral context is modest.

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: resource definition, valid filter fields, then pagination and endpoint. It is front-loaded and largely waste-free, though the filter-field list is dense enough to be borderline.

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 read-only list tool with 100% schema coverage and no output schema, it covers what an agent needs to call it: scope, valid filter fields, and pagination mechanics. Missing only routing guidance relative to get_item and the other list siblings.

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, but the description adds real value: the filters.field schema explicitly defers valid field names to this description, and it enumerates them (item_id, name, external_key, accounting_sku, item_type, custom_1..3), including that item_type is service or discount. That is meaningfully 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?

States a specific verb (List) and resource (items) and immediately defines the resource as 'the products, services and discounts that go on invoices, quotes and subscriptions, with their pricing tiers.' That domain definition, plus the contrast with the singular get_item sibling, lets an agent identify the tool 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?

Usage is implied by 'List items' and the enumerated filterable fields, which tells the agent this is the browsing/search entry point. However, it never states when to use this versus get_item for a single record, or versus other list tools, and gives no exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: which fields are filterable, that context_str takes a fixed set of context types, and the pagination contract ("pass next_offset as offset") plus the underlying endpoint GET /note.

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, front-loaded with what is listed, then filters, then paging. Every sentence carries information; the telegraphic "Paged: pass next_offset as offset" phrasing is slightly terse but not wasteful.

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

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

With four optional params, no output schema, and only a readOnlyHint annotation, the description supplies the filter vocabulary and pagination mechanics an agent needs to call it correctly. Minor gaps remain (default sort behavior, whether notes are returned with author/timestamps), and the entity list in sentence one (subscriptions, contacts) does not exactly match the context_str enum (billing_package, user).

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 goes further by naming the valid filter fields (context_str values and context_id) — information the schema explicitly defers to the description ("the list tool's description names the valid ones"). That is genuine added value over 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?

States a specific verb and resource ("List notes") plus the entity types notes hang off (customers, subscriptions, invoices, contacts, quotes, items), which cleanly separates it from the create_* and list_* siblings. An agent can identify this as the note-listing tool without opening the 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?

Usage is implied by the enumeration of attachable entities, but the description never states when to reach for this tool versus alternatives (e.g., the create_note sibling) or any prerequisite/limitation. No explicit when/when-not guidance is offered.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful behavioral context: the response omits line items, paging works by feeding next_offset back as offset, and the underlying call is GET /quote. It does not mention rate limits or result caps, but the added detail 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?

Purpose and the line-item caveat are front-loaded, and the filter enumeration is compact. It is a single dense block with no wasted sentences, though the filter list slightly crowds out readability compared to a structured breakdown.

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?

There is no output schema, and the description compensates by noting the list lacks line items and explaining pagination via next_offset. Combined with the fully documented input schema and the filter-field enumeration, an agent has what it needs; only the return envelope shape is left unspecified.

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 baseline is 3. The description exceeds that by enumerating the valid filter fields and spelling out the accepted values for quote_status_str and quote_status_state ('o = open, c = closed'), which the schema does not contain and which the schema explicitly defers to the description for.

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 ('List quotes') and immediately defines what a quote is and what the list representation contains ('proposals for a customer or lead; the list has no line items'). It also implicitly distinguishes itself from the sibling chargeover_get_quote by pointing to it for line items.

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 to get_quote when line items are needed, which is a real when-to-use-else decision. However, it gives no guidance on when to prefer this list over other quote-listing approaches or on scoping expectations (e.g. whether results are account-wide), so it stops short of full when/when-not 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?

readOnlyHint=true already establishes the safety profile, so the bar is lower. The description adds real context beyond the annotation: it scopes the result to the account's saved reports and reveals the returned fields, which matters because no output schema exists.

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

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

Three compact fragments, front-loaded with the action, followed by the routing hint and endpoint. Every clause earns its place with no waste.

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 no-param read tool with an empty schema and no output schema, the description supplies the missing return-shape information (report_id and name) and the follow-up tool. Sufficient, though it does not mention ordering or whether the list can be empty.

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 takes zero parameters, so the baseline is 4; there is no parameter syntax the description could meaningfully add.

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?

Specific verb (list) plus resource (account's saved reports), and it even names the returned fields (report_id and name). It is clearly distinguishable from chargeover_get_report and chargeover_run_report.

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: to run a report, use chargeover_run_report. This names the alternative and the condition selecting it, leaving nothing to inference for a list-then-run workflow.

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

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

Annotations already establish readOnlyHint=true, so safety is covered; the description goes further by disclosing pagination mechanics ('Paged: pass next_offset as offset'), the encoded status abbreviations (a/c/e/s), and the underlying endpoint GET /package. It stops short of describing default page size or reply shape, but that is minor given the read-only profile.

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?

Purpose and the alias clarification are correctly front-loaded, and every listed field is arguably load-bearing because the schema delegates field names to the description. However, the filter list is an unstructured run-on with no grouping or line breaks, which makes it harder to scan than it needs to be.

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 read-only, five-parameter list tool with 100% schema coverage there is no output schema, and the description compensates partially by noting the paged next_offset contract. Return-record contents and default ordering remain unspecified, but nothing required to invoke the tool 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?

Schema coverage is 100%, which alone would set a baseline of 3, but the description adds material value the schema explicitly defers to it for: the schema's 'field' property literally says 'the list tool's description names the valid ones', and the description does supply that enum-like list plus the decoding of status codes. It does not restate op semantics, which the schema already handles.

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 concrete verb+resource ('List subscriptions') and immediately resolves the naming ambiguity by noting the API calls them packages, then defines what a subscription is ('recurring billing plans of customers'). This distinguishes it cleanly from chargeover_get_subscription and the other list_* 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?

Usage is implied rather than stated: the filterable-field list and pagination hint tell the agent this is the tool for broad, filtered retrieval, and get_subscription is the obvious narrow alternative, but that contrast is never made explicit and no when-not-to-use condition is given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description usefully reinforces that this is read-only and clarifies the data universe (already-occurred payments/refunds/credits). It adds a concrete pagination behavior (feed next_offset back as offset), though it says nothing about rate limits or reply size beyond include_applied_to.

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 verb and scope, then the field inventory, then paging and the underlying endpoint. The long field run-on is dense but each item is load-bearing, and the trailing 'GET /transaction' is a minor implementation detail.

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 partially compensates by disclosing paging via next_offset and the include_applied_to reply-size tradeoff. It does not describe the returned transaction record shape, but for a list tool with a fully documented filter schema this is a minor gap.

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 earns above that by enumerating the valid filter field names — which the schema itself defers to ('the list tool's description names the valid ones'). Without this list an agent could not construct valid filters; the description does not, however, explain operator/value pairings beyond what the schema shows.

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 ('List transactions') and sharpens the scope with 'payments, refunds and credits that already happened; this tool only reads them.' It does not explicitly contrast itself with chargeover_get_transaction or the other list_* siblings, so a 4 rather than 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?

There is no explicit statement of when to choose this tool over chargeover_get_transaction or the other list_* tools, and no exclusions or prerequisites. The paging note ('pass next_offset as offset') is an operational hint, not tool-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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the HTTP route (GET /usage) and paging-continuation behaviour, which is modest extra context, but says nothing about return shape, limits, or auth; the offset paging guidance largely duplicates 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?

Three short sentences, front-loaded with purpose then filters then paging, with the endpoint last. 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 read-only list tool with fully documented params and no output schema, the definition covers purpose, filterable fields, and paging. Minor gaps remain around return fields and any tenant/permission scoping, but nothing needed 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?

Schema coverage is 100%, so the baseline is 3, but the description is the authoritative source for valid filter fields (line_item_id, external_key, from, to) — the schema itself defers to the description, so these names add real semantic value for the filters parameter.

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+scope: listing 'usage (metered billing) data points recorded against subscription line items'. This differentiates it cleanly from sibling list tools such as chargeover_list_subscriptions and chargeover_list_invoices, so an agent knows exactly what entity is returned.

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 implied usage context via the filterable fields and paging hints, but never states when to choose this tool over siblings or what prerequisite conditions exist (e.g. a subscription line item must already exist). Adequate but inferential.

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?

Adds real behavioral constraints beyond the readOnlyHint annotation: max 1000 rows per page, pagination (offset > 0) requires an order, and operators are field-type dependent (dates GTE/LTE/EQUALS, ids EQUALS, strings CONTAINS/DOES_NOT_CONTAIN). The POST endpoint is disclosed, clarifying that a 'read' is transported as a POST. Return shape/row structure is not described, but no output schema exists so some gap remains.

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-loads the core action and read-only guarantee, then layers filter syntax, operator rules, and paging constraints without filler. Dense but every clause carries actionable information; the trailing endpoint is the least essential element.

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 6-parameter, fully schema-documented tool with no output schema, the description covers filtering, pagination, and row limits adequately. It omits what a returned row/page looks like (e.g., next_offset usage is only in the schema) and any auth/permission requirement.

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, but the description adds genuine meaning the schema lacks: the operator-varies-by-field-type rule and a concrete filter example in the report's own field namespace. It also surfaces the order-required-for-paging rule that connects offset and order 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?

States a specific verb and resource ('Run a saved report and return its rows') and clearly scopes it as read-only execution as distinct from chargeover_get_report (fetch definition) and chargeover_list_reports (enumerate). An agent can distinguish it from every sibling 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?

Explicitly routes the agent to chargeover_get_report as the source of valid filter field names, which is the key prerequisite. It does not state an explicit 'do not use this if...' exclusion, but the workflow dependency is made concrete.

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?

Adds substantial behavioral context beyond the annotations: it declares a WRITE operation, partial-update semantics ('send only the fields to change'), replacement behavior ('replaces the previous values of the fields you send'), and explicit field-level exclusions. This directly clarifies what is destructive and what is out of scope, consistent with the destructiveHint annotation.

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?

Very concise and front-loaded with the WRITE marker and core action. Each clause adds distinct value: update scope, partial-send rule, exclusions, replacement semantics, and endpoint. No wasted text.

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 19-parameter schema and rich annotations, the description covers the essential invocation and safety context. However, with no output schema, it does not describe what the tool returns after a successful update, leaving a minor contextual gap for an agent expecting a response payload.

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 per-field descriptions already carry most parameter meaning. The description still adds a key usage rule: only send fields that should change, which is not expressed in the schema. It does not add field-specific details 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?

States a specific verb and resource: 'change fields of an existing customer'. Clearly distinguishes update from create, get, and list siblings. The write prefix and endpoint reinforce the action.

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

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

Explains when to use it: to change fields of an existing customer, and specifies that only changed fields should be sent. It also excludes payment methods, balances, and status. However, it does not explicitly route to alternative tools such as create_customer or get_customer.

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