Invoiced MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the write/non-destructive profile is covered. The description adds genuinely new context: notes are internal and 'nothing is sent' to the customer, which is a real side-effect disclosure beyond the annotations, plus the underlying POST /notes transport. It stops short of stating permissions or idempotency behavior in prose.

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 the operation type and free of filler. The trailing 'POST /notes' is mildly redundant with the tool name but useful transport context; overall the size is well matched to a simple write tool.

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

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

For a three-parameter write tool with no output schema and full schema coverage, the description covers purpose, target selection, and the key side-effect boundary (nothing is sent externally). It could add permission or duplicate-note behavior, but nothing essential 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%, so the baseline is 3, but the description adds a constraint the schema does not express: exactly one of invoice_id or customer_id must be supplied. The schema marks only 'notes' as required and does not enforce an either/or, so this sentence carries real semantic weight.

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

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

States a specific verb and resource ('add an internal note') plus both allowable targets ('to a customer or an invoice'), and the 'WRITE:' prefix immediately separates it from read siblings like invoiced_list_notes. An agent can pick this over the list/get note tools 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 description establishes context (internal notes on a customer or invoice) and the 'give exactly one' targeting rule, so usage is implied. However, it names no alternative tool and gives no when-not guidance, leaving an agent to infer that this tool and not invoiced_list_notes is the right call for creating a note.

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, destructive=false, idempotent=false, openWorld=true. The description adds real value beyond them: the write has no outbound communication and no financial movement, and the customer number is auto-generated if omitted. It stops short of noting duplicate-name behavior or that creation is non-idempotent (which the annotations imply but the text never reinforces).

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 the verb, resource, and safety profile. The trailing 'POST /customers' is compact endpoint context with no wasted words.

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

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

For a 17-parameter, nested-object write tool with no output schema and 35% param coverage, the description covers the essentials (purpose, required field, key side effects) but omits anything about the returned customer record/ID or duplicate handling. Adequate, but clearly incomplete.

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 17 parameters and only 35% schema description coverage, the description carries a heavy burden but only touches two fields: name (required) and number (default generated, which the schema already states verbatim). No light is shed on type, currency, metadata, payment_terms, or the address fields.

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

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

The description opens with a precise verb+resource ('create a customer in Invoiced') and the 'WRITE:' tag immediately separates it from the many read-oriented siblings (get_customer, list_customers). An agent can pick this 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?

It never states when to use this versus alternatives (e.g., create vs. get/list customer, or how to handle an existing customer). The remark that 'nothing is sent and no money moves' hints at low-risk usage but is not guidance about tool selection or preconditions.

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 say only readOnlyHint=false and destructiveHint=false; the description adds substantial behavioral context beyond that - the invoice is always a draft, never issued/emailed/charged, cannot trigger AutoPay, and requires at least one line item. It also discloses the underlying API call (POST /invoices with draft=true).

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

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

Three tight sentences, front-loaded with the write/draft nature, then the finalization condition, then the minimum requirement and API mapping. 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 an 11-parameter write tool with no output schema, the description covers the essential behavior and constraints. Return-value details are absent, and the description doesn't map to the injected customer_id reference, but the core call semantics are 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 coverage is 82%, so the schema already documents most parameters. The description still adds value by stating the 'at least one line item' constraint that justifies the required items array, going beyond per-parameter descriptions.

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

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

States a specific verb and resource ('create a DRAFT invoice for a customer') and emphasizes the draft state that distinguishes it from any future issue/finalize tool. An agent can identify this immediately as the invoice-creation tool among read-oriented siblings like invoiced_get_invoice and invoiced_list_invoices.

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?

Clearly frames this as creating a draft that must be finalized by a person in Invoiced before any issue/email/charge/AutoPay occurs, which implicitly scopes it. It does not name an alternative finalize/send tool or state explicit when-not conditions, so a 4 rather than 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the write/idempotency safety profile is covered. The description adds one genuinely non-obvious behavioral fact — no customer notification is triggered — plus the backing endpoint (POST /tasks). It says nothing about duplicate-creation behavior, assignment side effects, or required scopes.

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

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

Two short sentences, zero filler, with the operative mode ('WRITE:') and the resource front-loaded. The trailing 'POST /tasks' is terse reference metadata rather than 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 create tool with full schema coverage, four annotations and no output schema, the description covers what it makes, that it is a write, and that it has no customer-visible effect. Auth/permission requirements and error or validation behavior are the only meaningful omissions.

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 every parameter (name, action, user_id, due_date, customer_id) is documented in the schema itself, so the baseline is 3. The parenthetical 'call, write, email or review' loosely mirrors the action enum values but adds no syntax, default, or constraint detail 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 ('create a collection task for a customer') and even defines the resource in domain terms — a reminder to call, write, email or review. An agent can tell this apart from the read-only getters and listers in the sibling set, though it does not explicitly contrast with invoiced_add_note, the closest ambiguous sibling.

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: the domain gloss and the caveat 'Nothing is sent to the customer' tell the agent this is an internal reminder rather than an outbound communication. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. add_note vs create_task vs create_draft_invoice), so routing depends on 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds that line items, totals and balance are returned, but does not mention auth needs, error behavior for unknown ids, or pagination (not applicable here).

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

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

Two short, front-loaded sentences with zero filler: the payload contents come first, the underlying endpoint second. Nothing is wasted.

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

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

No output schema exists, so the description reasonably compensates by naming the returned fields (line items, totals, balance). This is sufficient for a single-record read tool with one well-documented parameter, though it could note behavior on invalid ids.

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?

Only one parameter, fully documented at 100% schema coverage ('Invoiced credit note id.' with exclusiveMinimum 0). The description's 'by id' merely restates the schema; 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 (get) and resource (credit note by id) plus what the response contains: line items, totals and balance. It is clearly distinguishable from sibling list tools like invoiced_list_credit_notes, though it does not name them 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?

The phrasing 'One credit note by id' implies the fetch-a-single-record use case and contrasts implicitly with the list variant, but there is no explicit when-to-use, prerequisite, or named alternative. Usage is left 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful scope about what data comes back (contact details, terms, autopay, credit hold, metadata) but says nothing about auth requirements, error behavior for a missing id, or pagination/expansion options.

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 that front-loads the core purpose and ends with the route; no filler. The field list is long but each entry earns its place by telling the agent what the response contains.

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 notable returned fields, which is exactly what an agent needs to judge relevance. Missing only edge-case behavior (unknown id, permissions), which is minor for a read-by-id endpoint.

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

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

Schema coverage is 100% and the schema itself documents the id as 'numeric; not the customer number'. The description only echoes 'by id', adding no syntax or format detail beyond the schema, 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 and resource ('One customer by id') plus the HTTP route GET /customers/{id}, and enumerates the fields returned, so the agent knows exactly what it retrieves. It does not explicitly contrast with the nearby siblings get_customer_balance or list_customers, but 'by id' does implicit work in separating it from the list tool.

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

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

'by id' implies the lookup-by-identifier use case and the single-customer scope, but the description never states when to prefer this over invoiced_get_customer_balance or invoiced_list_customers, nor any prerequisites. Usage is inferable 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, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered and the description needn't repeat it. The description does add behavior worth knowing — the balance is expressed in the customer's currency unless overridden — but says nothing about auth requirements, rate limits, or freshness of the computed balance.

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 stating what the balance comprises, followed by the endpoint for API-literate agents. No filler and no restatement of the title, which already says 'Get customer balance'.

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 must carry the return shape, and it does name the three balance components. It omits units/format details (sign convention for available credit, whether past due is a subset of outstanding), which keeps it from a 5, but for a two-parameter read tool it is essentially 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%, so both parameters are already documented, and the baseline for that situation is 3. The description's `currency` reference and the 'default: the customer's currency' phrasing reinforce the schema's documented default but add no new syntax or constraint detail.

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 resource (customer balance) and enumerates exactly what the value contains: total outstanding, past due, and available credit. That distinguishes it from siblings like invoiced_get_customer, which returns the customer record rather than a financial summary. It stops short of naming the sibling it differs from, so it lands at 4 rather than 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 when-to-use guidance and no alternatives named, even though invoiced_get_customer and invoiced_list_invoices are plausible neighbors an agent might confuse it with. The only routing signal is the raw endpoint path, which assumes the agent knows the Invoiced API surface.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds value by disclosing what the call returns — line items, totals, deposit and approval state — which is meaningful given there is no output schema. It stops short of describing not-found behavior or format of the response.

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

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

Two short sentences, zero filler, with the core operation and returned content front-loaded. The endpoint string is a compact, useful anchor for developers.

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-record read with no output schema, the description covers resource, identifier, and returned content, which is sufficient to invoke correctly. It omits only edge behavior such as invalid or missing ids, a minor gap given the tool's simplicity.

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

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

Single parameter with 100% schema description coverage ('Invoiced estimate id.'), so the schema already carries the semantics. The description only restates 'by id' and adds no type, range or format detail beyond the schema's integer/exclusiveMinimum constraint. 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) and resource (estimate) scoped to a single record by id, then enumerates the payload it returns (line items, totals, deposit, approval state). This clearly separates it from invoiced_list_estimates and from the sibling get_* tools for other resources.

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: fetch one estimate when you already know its id. The description never states when to prefer this over invoiced_list_estimates for discovery, nor any prerequisite beyond the id. Adequate for a trivial lookup, but no explicit routing 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, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds real value by disclosing the response contents (totals, balance, line items, PDF links) since no output schema exists. It does not mention auth requirements or pagination, but for a single-resource GET that gap is minor.

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 compact sentences: the return surface is front-loaded and the expand behavior plus endpoint follow. No filler, no repetition of the title.

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 enumerated field list is what makes this definition usable, and it is present. The endpoint path and expand semantics round it out; only edge concerns like permissions or error behavior are 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 description coverage is 100%, so both parameters are already documented, making 3 the baseline. The description adds only a light gloss on expand ('replaces ids with full objects') that largely restates the schema's 'expand into full objects' and the enum example already present.

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) and resource (invoice) with scope ('One invoice by id'), which implicitly and effectively separates it from invoiced_list_invoices. It also enumerates the returned data surface, so an agent knows exactly what this call yields.

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 id' and the sibling list makes the list-vs-get split inferable, but the description never states when to prefer this tool over invoiced_list_invoices or invoiced_get_credit_note. The only routing hint (find the id with invoiced_list_invoices) lives in the schema, not the description.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: the 404 when no plan exists, the shape of the returned data (installments with dates, amounts, balances, approval status), and the underlying endpoint.

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

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

Two tight sentences: payload first, then failure mode and endpoint. Nothing is redundant and the most decision-relevant information (what it returns) leads.

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 with no output schema, the description covers resource identity, return payload, error case, and endpoint. The only gap is that return values are only summarized rather than typed, which is acceptable but keeps it out of the top band.

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% for the single invoice_id parameter, so the schema already documents it fully. The description adds no format, range, or sourcing detail beyond what the schema supplies, which is the expected baseline when the schema does the work.

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

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

The description names the specific resource (the payment plan attached to an invoice) and enumerates its payload, which implicitly separates it from the sibling invoiced_get_plan (a plan catalogue) and invoiced_get_invoice. It stops short of naming those siblings outright, so differentiation is inferable rather than explicit.

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

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

Usage is only implied: the agent can infer this is the tool for fetching one invoice's installment schedule, but there is no statement of when to prefer it over invoiced_get_invoice or invoiced_get_plan, and no prerequisites. The 404 note is a failure condition, not routing 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying HTTP operation (GET /items/{id}) and the slug-like id format, but says nothing about what a catalog item contains or how lookups behave for missing ids.

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 terse fragments with zero waste, front-loading the resource and following with the endpoint and id example. Nothing is padded or repeated.

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

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

For a single-parameter read tool with annotations covering safety, this is nearly sufficient. The one remaining gap is that no output schema exists and the description does not hint at the shape of a catalog item, so the agent must discover the return structure at call time.

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 an extra point by giving a concrete id example ("delivery"), which clarifies that ids are human-readable slugs rather than opaque numeric ids — information the schema's plain "string" type does not convey.

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: fetch a single catalog item by id, with an example id ("delivery"). The singular "One catalog item" implicitly separates it from the plural sibling invoiced_list_items, though that sibling is never named.

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

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

No when-to-use or when-not-to-use guidance, and no alternatives named. The only routing hint (id comes from invoiced_list_items) lives in the schema, not the description, so the description itself gives no usage context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description usefully adds that the applied_to relationship data is included via the include parameter, but says nothing about not-found behavior or response shape beyond that field.

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 plus the raw endpoint template, front-loaded with the resource and scope. No filler, nothing redundant.

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 carries the return-value burden and partially does so by naming the applied_to expansion. For a simple single-entity GET with covered annotations and a fully documented param, this is nearly complete, though it omits error/empty cases.

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

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

Schema description coverage is 100% and the single payment_id param is already documented in the schema, so the baseline is 3. The description adds only that the fetch expands applied_to, which is more a return-value note than a parameter semantic.

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 (get one payment by id) and adds scope by naming the applied_to expansion, which surfaces which invoices/credit notes the payment settled. It does not explicitly distinguish itself from invoiced_list_payments, but the singular framing makes the difference inferable.

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 singular 'One payment by id' framing versus the list sibling, but there is no explicit when-to-use, when-not-to-use, or prerequisite statement (e.g., payment must exist, use list_payments to discover ids).

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without description help. The description adds only the underlying REST route (GET /plans/{id}), which is modest additional context and no detail on failure modes or response shape.

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

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

Two short clauses, front-loaded with the essential purpose, so there is little waste. The trailing REST endpoint notation is marginally redundant with the tool's implicit HTTP nature but does not bloat the definition.

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

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

For a single-parameter read tool with full schema coverage, no output schema, and annotations carrying the safety profile, the definition supplies everything needed to invoke it correctly. Only the lack of explicit sibling routing keeps it from a 5.

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

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

Schema coverage is 100% and the schema already describes plan_id including its source (invoiced_list_plans). The description restates that it is a string id but adds no new syntax or format guidance, 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) and resource (one subscription plan) keyed by id, which is enough for an agent to distinguish it from the write/create siblings. It does not explicitly contrast with invoiced_list_plans, which is the closest sibling, so it falls 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?

There is no explicit when-to-use or when-not-to-use statement, but the single-id retrieval framing plus the schema note that the id comes from invoiced_list_plans implies the context well enough. No exclusions or alternatives are named.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that by naming what the response contains (MRR, contract terms, recurring total), which matters because there is no output schema. It stops short of noting auth needs or error behavior for a missing id.

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 compact sentences, front-loaded with the resource and its returned fields, with the endpoint appended as a useful identifier. No filler.

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

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

For a simple read-by-id tool with full schema coverage, complete annotations, and a description that enumerates the returned fields in place of an output schema, an agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100% and the single parameter carries its own description ('Invoiced subscription id.'). The description's 'by id' adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description gives a specific resource ('One subscription by id') and enumerates the returned surface (plan, add-ons, billing period, contract terms, recurring total, MRR), plus the underlying endpoint GET /subscriptions/{id}. It is clearly a single-record fetch and distinguishable from invoiced_list_subscriptions, though it never names that sibling 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 when-to-use or when-not-to-use guidance. An agent must infer from the phrase 'by id' that this is the single-record counterpart to invoiced_list_subscriptions, and no prerequisite (e.g. needing an id from a list call) is 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the REST endpoint and a useful semantic note that the primary contact is 'copied on communications', but says nothing about pagination limits or result ordering 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?

Two sentences, zero filler: the resource and its returned fields come first, the endpoint last. Every clause carries information and nothing is repeated from the schema.

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, enumerating the returned fields (name, title, email, phone, primary, SMS-enabled) is genuinely compensating information. Combined with comprehensive parameter schemas and read-only annotations, this covers what an agent needs, with only pagination/ordering behavior left implicit.

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 every parameter (page, sort, per_page, customer_id) is documented in the schema itself. The description only implies that customer_id scopes the call; it adds no syntax or format detail beyond the schema, 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?

States a specific verb (List) and a precisely scoped resource (contacts belonging to one customer), and enumerates the returned fields. The scope phrase 'of one customer' distinguishes it from invoiced_list_customers and invoiced_get_customer, though no sibling is 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?

Usage is implied: fetch contacts for a known customer id. There is no explicit when-to-use guidance, no mention of when to prefer invoiced_get_customer instead, and no note about paginating through large contact lists (that detail lives only in the schema).

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds the returned field set and the HTTP endpoint but says nothing about pagination behavior, defaults, or result ordering beyond what the schema provides.

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

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

Two short sentences with zero filler; the resource and returned fields are front-loaded and the endpoint follows compactly. 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?

With no output schema, the description usefully enumerates the returned fields and status values, which compensates well. It falls slightly short by omitting any note on pagination behavior or result limits, though those are largely covered by the schema parameters.

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

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

Schema description coverage is 100%, so all nine parameters are documented in the schema itself; the baseline is 3. The description adds no parameter-level detail (e.g. filter syntax or date semantics) beyond what the schema already states.

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 ('credit notes'), and enumerates returned fields including the status value set. It's clearly distinguishable from single-record tools like invoiced_get_credit_note by name and description, though it doesn't explicitly contrast with it.

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' and the GET endpoint, but there is no explicit when-to-use context, no mention of alternatives (e.g. invoiced_get_credit_note), and no stated prerequisites. An agent can infer the intent but gets no routing 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, destructiveHint=false and openWorldHint, so the safety profile is covered by structured data. The description adds the GET /customers endpoint and the filterable axes, but discloses nothing about pagination behavior, result volume, auth requirements, or rate limits beyond what the schema/annotations provide.

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 compact sentences: the resource and returned fields first, then the filter capabilities, then the endpoint. No filler, well front-loaded. The field enumeration is dense but each item carries selection 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?

For a read-only, zero-required-parameter list endpoint with no output schema, the description is adequately complete: it enumerates the returned fields (compensating for the missing output schema) and covers all filter axes. It stops short of pagination/result-size guidance, which the schema party covers via page/per_page.

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

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

Schema description coverage is 100%, so the schema already explains every parameter (page, sort, filter, metadata, per_page, open_balance, updated_after, payment_source). The description's filter list maps to a subset of these but adds no syntax, format, or constraint detail beyond the schema; 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+resource ('List customers (accounts receivable debtors)') and enumerates the fields returned (name, number, email, payment terms, currency, autopay/chasing settings, owner). Combined with the sibling set (invoiced_get_customer, invoiced_create_customer), an agent can immediately tell this is the collection-enumeration tool rather than a single-record fetch or a write.

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

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

The description names the available filter dimensions ('open balance, saved payment method, update time or any exact-match column'), which implies when the tool is useful, but never states when to prefer it over invoiced_get_customer or how it relates to the other list_* tools. Usage is implied rather than asserted, and there are 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description still adds value by disclosing what the records contain (including the status lifecycle draft/not_sent/sent/approved/invoiced/declined/voided) and the resulting-invoice linkage, which is not derivable from the annotations or input 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?

A single dense sentence plus the endpoint path, with the core purpose front-loaded. The trailing 'GET /estimates' is mildly redundant but economically conveys the underlying call.

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 parameters and no output schema, the description supplies the return-field inventory and status vocabulary an agent needs to interpret results. Pagination semantics live in the schema, so 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% across all 9 parameters (page, sort, filter, metadata, date bounds, customer_id), so the schema already carries parameter meaning. The description adds no syntax or format detail about those parameters, 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?

Clear verb+resource (list estimates) with an inline gloss that these are quotes, plus an enumeration of the returned fields (customer, status, expiration, deposit, totals, resulting invoice). It does not explicitly contrast with the sibling invoiced_get_estimate for single-record reads, so it stops short of a 5.

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

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

The list nature makes the basic use case obvious, but there is no explicit when-to-use guidance, no mention of paginating via next_page, and no pointer to invoiced_get_estimate when a single estimate is wanted. Usage is implied 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, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context — the 'newest first' ordering and the shape of each event (type, time, object, actor) — but says nothing about pagination behavior or result volume.

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

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

Front-loaded with the core purpose, then the optional filter, then the endpoint — two tight sentences with no padding. The trailing 'GET /events' is mildly redundant but otherwise the text is efficient.

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

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

With no output schema, the description usefully carries the return-value burden by describing the event content. Combined with annotations covering safety and the schema covering pagination, an agent has enough to call this 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 schema already documents all four params including pagination and the related_object pairing rule. The description's 'only the events of one object' restates the filter intent without adding syntax 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 clear resource (the activity feed of events) and enumerates the event fields, which tells the agent exactly what kind of data comes back. The resource (events) is distinct from the list_customers/list_invoices siblings, though it never explicitly contrasts itself with them.

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 one usage cue — 'optionally only the events of one object' — which maps to the related_object filter. But it gives no when-to-use-vs-alternatives guidance and no exclusions or prerequisites, leaving usage mostly 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds real value beyond that by disclosing the fields present in each returned record — important because there is no output schema — plus the status vocabulary (draft, sent, past_due, etc.) that the schema does not enumerate. It omits pagination behavior and rate limits, keeping it below 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?

Two sentences, front-loaded with the resource and its returned shape, followed by filtering and the endpoint. The status enumeration is long but carries information absent from the schema, so it earns its space.

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 10-parameter, zero-required list tool with nested objects and no output schema, the description supplies the return-field inventory and filtering overview that structured fields cannot. Pagination mechanics live in the schema, so the only genuine gap is the absence of output-shape/pagination prose.

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 all 10 parameters (including the nested filter and metadata objects) are already documented in the schema. The description reinforces the filter categories at a high level but adds no format or syntax detail beyond what the schema provides, 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?

Specific verb+resource (list invoices) with an explicit enumeration of returned fields (number, customer, status, dates, totals, balance, line items) and the endpoint GET /invoices. It does not name the sibling it should be chosen over (e.g. invoiced_get_invoice for a single record), 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?

The filter clause ("Filter by customer, paid flag, invoice date range, update time or any exact-match column") implies when the tool is appropriate, but there is no explicit when-to-use vs. when-not guidance and no reference to the single-invoice or other list siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description goes beyond them by disclosing the shape of the response (id, name, currency, unit cost, type, taxable) and the underlying GET /items endpoint, which matters because there is no output 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?

Two compact sentences, front-loaded with the resource and the returned fields, followed immediately by the actionable linkage to draft-invoice creation. Nothing is padded; even the endpoint hint is a single token.

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, listing the returned fields is the right compensating move, and pagination/sorting/filtering are fully documented in the schema. Minor gap: it does not mention the paging envelope (next_page/total) or that results may span multiple pages, though the page param hints at it.

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% (page, sort, filter, per_page, updated_after are all documented, including next_page chaining and filter syntax), so the schema carries the burden. The description adds nothing about parameters beyond the `catalog_item` naming note, which is not a parameter of this tool; 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 ('List the item catalog (products and services)') and enumerates the fields returned, so the agent knows exactly what data comes back. It is naturally distinguishable from sibling list tools, but it never explicitly differentiates itself from invoiced_get_item or the other invoiced_list_* endpoints.

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?

'Use item ids as `catalog_item` when creating a draft invoice' links the result to a concrete downstream use (invoiced_create_draft_invoice), which implies why you would call this. However, it gives no guidance on when to prefer this over invoiced_get_item for a single item, and no exclusions or preconditions.

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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds two behavioral facts beyond the annotations: results are ordered newest-first and the two id filters are mutually exclusive. Pagination behavior is left to the schema rather than described, 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?

A single front-loaded sentence: what it lists, in what order, and the filter rule. The trailing route list is compact and adds API mapping value. 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 read-only list tool with full schema coverage and annotations, the description supplies the filter rule and ordering. Since no output schema exists, it does not describe the returned note shape, but that is the only material omission for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description beats that baseline by stating the mutual-exclusivity constraint between invoice_id and customer_id, which the schema property descriptions ('Only this invoice's notes') do not convey. Nothing is added for page/per_page.

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 (collection notes) plus the scoping modes: one customer, one invoice, or all. Sort order ('newest first') is included, and the sibling invoiced_add_note is clearly a different operation (write vs. list). An agent can distinguish it from every other list_* sibling by the resource.

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 selection rule: supply exactly one of customer_id/invoice_id, or neither to get everything. That is strong routing guidance. It stops short of naming alternative tools (e.g., for a single note) or stating when this tool is the wrong choice, so it doesn't reach 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Read only' is consistent with them. It adds the enumerated response fields, but says nothing about pagination continuity, result size, or the open-world scope, so with annotations carrying the safety profile a 3 is appropriate.

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 that front-loads the core action and then the returned fields, with 'Read only. GET /payments.' as terse supporting facts. Every clause carries information; no 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?

With no output schema, the description usefully enumerates what a payment record contains, which is exactly the gap that needs filling. Pagination mechanics are handled by the schema, so the only remaining soft spot is the absence of guidance on narrowing results via date/customer filters.

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 page, sort, filter, start_date/end_date, customer_id, per_page and updated_after are all documented in the schema itself. The description adds no syntax or semantic detail beyond that, matching the baseline for schema-covered 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?

Specific verb+resource ('List payments received') with an enumeration of the returned fields (customer, date, amount, unapplied balance, method, reference, matched/voided status), which lets an agent distinguish it from the singular invoiced_get_payment. Sibling differentiation is implicit rather than stated explicitly, so it stops short of a 5.

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

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

Usage is implied by 'List payments received' and the read-only framing, but the description never states when to prefer this over invoiced_get_payment or how the date/filter parameters select a subset. No explicit alternatives or exclusions are 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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds only the 'GET /plans' endpoint, which is essentially restated by those annotations – it says nothing about pagination behavior, auth requirements, 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?

Two short fragments, front-loaded with the purpose and the returned fields. The trailing 'GET /plans' endpoint is largely redundant with the tool name, but nothing is verbose or 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, enumerating the returned plan fields is genuinely useful, but the description omits the pagination envelope (next_page is referenced by the page param in the schema) and any indication of filtering/sorting support. Adequate but incomplete for a list tool with nested filter objects.

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 all five params (page, sort, filter, per_page, updated_after) are fully documented in the schema. The description adds no parameter detail, 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?

Clear verb+resource: 'List subscription plans' with an enumerated set of returned fields. It is distinguishable from invoiced_get_plan by the plural 'list' vs singular 'get', though the description never names that sibling explicitly to sharpen the contrast.

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

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

No statement of when to use this versus invoiced_get_plan, invoiced_list_subscriptions, or other list siblings, and no prerequisites or filtering guidance. The agent must infer usage purely from the name.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the GET endpoint, which is modest value but no pagination, rate-limit, or result-shape detail. With annotations carrying the behavioral burden, a 3 is appropriate.

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 efficient sentence front-loads the verb and resource, then lists fields and the endpoint. No filler, though the trailing endpoint reference is low-value given the tool name.

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 enumeration of return fields (customer, plan, quantity, billing period, status, recurring total, MRR, contract renewal) usefully compensates by describing the result shape. Combined with the fully documented parameter schema, the agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters including pagination, sort, filter, and metadata syntax. The description adds no parameter-level detail, though the enumerated status values (not_started, active, past_due, finished, canceled) hint at filterable states. Baseline 3 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 (recurring subscriptions) and enumerates the key fields returned, so an agent knows exactly what this retrieves. It does not explicitly differentiate itself from sibling invoiced_get_subscription, but the list-vs-get distinction is inferable 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?

There is no when-to-use guidance, no stated alternatives, and no mention of when this should be preferred over invoiced_get_subscription for a single record. The agent must infer usage entirely from the name.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the returned field list and the raw endpoint (GET /tasks); it says nothing about pagination behavior or result limits beyond what the schema documents.

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 with the returned fields front-loaded in a parenthetical and the endpoint appended. No filler, nothing repeated from the schema.

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 full schema coverage and no output schema, listing the returned fields compensates well for the missing return value documentation. The only gap is pagination/result-set guidance, which the page and per_page descriptions largely cover indirectly.

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 all five parameters (page, sort, complete, per_page, customer_id) are already fully documented in the schema. The description's mention of 'whether complete' lightly echoes the complete filter but adds no syntax or format detail. 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 (collection tasks) and enumerates the returned fields, so the agent knows exactly what comes back. It does not distinguish itself from sibling list tools (e.g. invoiced_list_events or invoiced_list_notes) beyond the resource noun, 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?

Usage is only implied: the name and endpoint make it obvious this is the read path for tasks, and 'whether complete' hints at filtering. There is no statement of when to prefer this over invoiced_create_task, invoiced_list_events, or per-customer fetching, and 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description earns credit beyond that by enumerating the response fields (id, name, value, percentage, inclusive, currency), which partially substitutes for the missing output schema. It still omits pagination behavior such as the next_page follow-up, so it does not reach the top of the scale.

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 clauses: the field list first, then the endpoint. Zero filler, fully front-loaded, and every token is either a returned field name or the route.

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 paginated read-only list tool with no output schema, the return-field enumeration is the key thing the description must supply and it does. Pagination and filtering are fully covered by the schema, leaving only minor gaps such as the behavior of next_page and default ordering.

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 page, sort, filter, per_page and updated_after all documented in the schema itself. The description adds no parameter meaning whatsoever, so the baseline 3 applies – the schema carries the full burden here.

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?

Names a specific verb and resource ("List tax rates") and even enumerates the returned fields, so an agent can tell it apart from the sibling list_* tools, which target entirely different resources. It stops short of the 5 mark only because it never contrasts itself with any alternative call 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?

There is no when-to-use guidance, no prerequisite mention, and no alternative named. The only instruction ("GET /tax_rates") is a transport detail rather than a routing hint, leaving the agent to infer that this is the read path for tax-rate data.

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