Orb MCP by usefulapi

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

The annotations only supply a title and destructiveHint=true, so the description does most of the work: it discloses prerequisites and maps to the underlying POST /customers endpoint. However, 'additive' arguably softens the destructiveHint=true annotation and creates ambiguity about what 'destructive' means for a create call, and nothing is said about duplicate-email behavior, permission requirements, 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?

Three short, front-loaded sentences with zero filler: purpose, prerequisites, and endpoint. Nothing needs to be trimmed and the most important information comes first.

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 eight-parameter mutation tool with no output schema, the description covers required inputs and the API route but omits what is returned (e.g. the new customer id), error/duplicate handling, and any permission context. Adequate but with clear gaps given the tool's 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 description coverage is 100%, so the schema already documents all eight parameters including the two required ones and the payment_provider enum. The description only restates the two required fields, adding no syntax, default, or interaction detail beyond what the schema provides — 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 ('Creates a new customer in Orb'), which cleanly separates it from the orb_get_*/orb_list_* siblings that read customer data. It does not explicitly name orb_update_customer as the alternative for modifying existing records, but the create-vs-read/modify distinction is obvious from the verb.

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

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

The description gives preconditions ('Requires name and a valid email') and the 'additive' qualifier implies this is for net-new records, but it never says when to reach for orb_update_customer instead, nor what happens if the email already exists. 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the underlying REST mapping (GET /customers/{customer_id}), which is mild but useful context; it does not disclose 404 behavior, auth requirements, or what the response contains.

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 waste, with the core action front-loaded ahead of the endpoint detail. Nothing is padded.

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

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

For a one-parameter read tool this is close to sufficient, but with no output schema the description gives no hint about the returned customer object or failure cases. Adequate minimum viable coverage, not complete.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents customer_id fully. The description adds no format, prefix, or example detail beyond 'Orb customer id', making 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 (Fetch) and resource (a single customer), scoped to lookup by Orb customer id. The phrase 'Orb customer id' implicitly separates it from orb_get_customer_by_external_id, but the sibling is never named, so the agent must infer the distinction.

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: call this when you have an Orb customer id. It does not state when to prefer this over orb_get_customer_by_external_id or orb_list_customers, nor any error/prerequisite 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 already declare readOnlyHint=true, so the safety profile is covered, and the description adds the underlying REST endpoint (GET /customers/external_customer_id/{external_customer_id}). It does not disclose what happens when the external id is unknown (empty body vs. 404) or any rate-limit behavior, so it adds only modest context 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?

Two short sentences, front-loaded with the purpose and followed by the endpoint mapping. Nothing is redundant or padded.

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

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

For a one-parameter read tool with readOnlyHint and no output schema, the description covers the essentials: what it returns conceptually and which identifier to supply. The main omission is failure behavior for an unmatched external id, a minor gap rather than a blocking one.

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 a single parameter with 100% schema description coverage, so the schema already documents it; the description only restates 'your external customer id'. Baseline 3 applies since the schema does the heavy lifting and the description contributes no additional syntax or format guidance.

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

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

States a specific verb ('Fetch') and resource ('a single customer') and pins the lookup key to the external customer id, which implicitly separates it from the sibling orb_get_customer. It never names that sibling or states the contrast explicitly, so differentiation is inferred rather than spelled out.

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 your external customer id' implies the selection condition for this tool over orb_get_customer, but there is no explicit when-to-use/when-not statement or named alternative. Usage is left to the agent's 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?

readOnlyHint=true already tells the agent this is a safe read, so the description isn't carrying the safety burden. It adds the underlying endpoint and the customer/timeframe scoping, but says nothing about the response shape, how view_mode changes the result, or any pagination behaviour.

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 no filler; the purpose leads and the endpoint reference follows. The endpoint sentence is marginally useful for traceability, though it is the least essential part.

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 and five parameters, the description should at least sketch what comes back (per-customer cost breakdown, how group_by and view_mode alter it). It covers the call but leaves the return value entirely unspecified, which is adequate but thin for a costs-reporting 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 every parameter is already documented in the schema and the baseline of 3 applies. The description adds no syntax, format, or default information beyond the timeframe notion already implied by the name.

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 with scope: 'Get costs incurred by a customer over a timeframe', and pins it to the exact endpoint GET /customers/{customer_id}/costs. The 'customer' qualifier implicitly separates it from the sibling orb_get_subscription_costs, but the description never names that sibling or any other, so differentiation is left to inference.

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 indication of when to prefer this over orb_get_subscription_costs or orb_get_customer_credits, and no prerequisites. The 'over a timeframe' phrasing hints at a scoping condition but stops short of telling the agent when this tool is the right choice.

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, non-mutating read, so the description only needs to add context. It adds the underlying endpoint (GET /customers/{customer_id}/credits) and confirms the return is per-currency balances, but says nothing about pagination, ordering, or how blocks versus balances relate. Useful but not rich behavioral disclosure.

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

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

Two short sentences, purpose front-loaded before the endpoint reference, with no filler. The endpoint line is arguably redundant metadata but is compact enough to justify its place for agents that reason about API routes.

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 read-only lookup with no output schema, the description tells the agent what is retrieved and at what granularity (per currency), which is enough to call it correctly. Minor gaps remain around result shape and pagination, but the safety profile is already covered by annotations.

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 customer_id, currency, and include_all_blocks are already documented in the schema; baseline is 3. The description's 'by currency' phrase loosely echoes the currency filter but adds no format, default, or interaction 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 (Get), resource (customer's credit balances), and the grouping dimension (by currency), which distinguishes it from the ledger-oriented sibling orb_get_customer_credits_ledger. It does not explicitly name that sibling, so the differentiation is left to inference rather than stated.

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, and no pointer to the nearest alternative (orb_get_customer_credits_ledger) even though the two tools are easy to confuse. The scope phrase 'by currency' implicitly indicates the use case, but nothing in the text tells an agent when to prefer this over the ledger endpoint.

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 genuinely useful context with 'append-only,' signaling an immutable historical record rather than a mutable balance, but says nothing about pagination, result volume, or ordering beyond what the schema shows.

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 the purpose front-loaded and no wasted words. The REST endpoint reference is a mild redundancy but can aid doc cross-referencing.

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 would ideally hint at what a ledger entry contains, but for a simple filtered read with a fully documented parameter set the omission is tolerable. It is minimally complete rather than richly so.

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 (limit, cursor, currency, entry_type, customer_id) are already documented in the schema. The description adds no filter semantics or value examples beyond that, 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?

States a specific verb and resource ('Get the append-only credit ledger for a customer') and the 'append-only' qualifier implicitly distinguishes it from the sibling orb_get_customer_credits. It does not explicitly name that sibling or contrast the two, so it falls short of full 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?

No guidance on when to use this versus orb_get_customer_credits or orb_get_customer_costs, and no stated prerequisites or exclusions. Usage must be inferred entirely from the tool name and resource noun.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the REST endpoint path, which is structural trivia rather than behavioral context such as error behavior when the id is unknown or the shape/limits 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, front-loaded sentences with no filler. The second sentence ('Orb API: GET /invoices/{invoice_id}') is largely redundant for an agent and does not earn much of its place.

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

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

For a simple one-parameter read tool this is close to adequate, but with no output schema the description says nothing about what the invoice object contains or what happens on an invalid id, leaving an avoidable 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 description coverage is 100% for the single invoice_id parameter, so the schema carries the burden. 'By id' adds no format, prefix, or example detail 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 and resource ('Fetch a single invoice by id'), clearly distinguishing a single-record fetch from list operations. It does not, however, differentiate itself from close siblings like orb_get_upcoming_invoice or orb_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?

No when-to-use guidance is given. An agent must infer from 'single' that this is not a list call, and nothing tells it when to prefer this over orb_list_invoices or orb_get_upcoming_invoice.

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 only adds the REST endpoint mapping, which is not behavior an agent needs; it says nothing about 404/not-found handling, auth, or what an 'item' contains. With annotations carrying the safety profile, this adds little.

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, front-loaded with the core action; nothing is padded. The trailing API endpoint reference is mildly redundant but not 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?

For a simple single-entity read with safety annotations and no output schema, the description is adequate but thin: it never says what an item represents or how a missing id behaves, which is the main gap an agent might hit.

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 there is a single item_id parameter documented as 'Orb item id.' The description's 'by id' adds no meaning 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 (Fetch) and resource (a single item) with the lookup key (by id), and the REST mapping GET /items/{item_id} confirms the scope. It does not explicitly name the sibling orb_list_items, but 'single item' implicitly contrasts with listing.

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 and no alternative named; the agent must infer that this is for retrieving one known item versus orb_list_items for enumeration. No prerequisites or error conditions are mentioned.

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 underlying API route (GET /plans/{plan_id}), which is mild extra context, but it says nothing about error behavior (e.g., unknown id) or anything 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?

Two short, front-loaded sentences with no filler. The purpose comes first and the API route supports it without 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 simple single-resource read with complete schema coverage and a readOnly annotation, the description covers what an agent needs. Minor gaps (error behavior) are acceptable given the low complexity and absent output schema.

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

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

Schema description coverage is 100% and there is a single well-documented plan_id parameter. The description adds no format or syntax detail beyond what the schema already provides, 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?

Specific verb (Fetch), resource (plan), and scope (single, by id) are all stated. The 'single plan by id' phrasing implicitly distinguishes it from the sibling orb_list_plans, though it never names the alternative 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 only implied: 'by id' suggests retrieval when a plan_id is known rather than listing. There is no explicit when-to-use or when-not-to-use guidance against orb_list_plans or other get_* 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the underlying endpoint (GET /prices/{price_id}), which is mildly useful context, but says nothing about not-found behavior, permissions, 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 sentences, zero waste, with the core purpose front-loaded and the API mapping relegated to a secondary clause.

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-resource getter with full parameter documentation and a readOnly annotation, this is nearly complete. The only gap is that no output schema exists and the description does not hint at what a price object contains.

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 only one parameter exists, so the schema already fully documents price_id. The description adds no format or sourcing detail beyond 'by id', 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?

States a specific verb ('Fetch') and resource ('a single price'), and the word 'single' implicitly contrasts with the orb_list_prices sibling. It does not name that alternative explicitly, so it falls just short of the top band.

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 'by id' phrasing implies you must already have a price_id, which is a usage condition, but there is no explicit when-to-use guidance or stated relationship to orb_list_prices for discovery.

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 non-mutating read, so the annotation carries the safety profile. The description adds the underlying API mapping (GET /subscriptions/{subscription_id}), but says nothing about behavior on an unknown id, cancellation status, 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 sentences, front-loaded with the action and resource, with the endpoint as compact supplementary context. 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 one-parameter read tool with readOnlyHint covering safety and 100% schema coverage, the description is sufficient to invoke correctly. The only gap is sibling disambiguation against the other subscription sub-resource getters, which the description does not address.

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 only parameter (subscription_id) is fully documented in the schema. The description's 'by id' merely restates what the schema already defines, adding no format, prefix, or validation detail. 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 (Fetch) and resource (a single subscription by id), which clearly distinguishes a single-record read from orb_list_subscriptions. It does not, however, name or differentiate itself from the other subscription-scoped readers (orb_get_subscription_costs, orb_get_subscription_schedule, orb_get_subscription_usage).

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 'Fetch a single subscription by id' – the agent can infer this is the tool for retrieving one subscription when the id is known. There is no explicit when-to-use guidance, no exclusion, and no routing to siblings such as orb_list_subscriptions or the costs/schedule/usage variants.

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 underlying endpoint (GET /subscriptions/{subscription_id}/costs), which is mild extra context but says nothing about aggregation behavior, default timeframe, pagination, or response size for what is clearly a reporting/aggregation call.

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

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

Two short sentences, front-loaded with the purpose and no filler. The endpoint citation is marginally useful for API-savvy callers but borders on redundancy with 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 description should carry some sense of what comes back (cost breakdown by price, periodic vs cumulative series), and it does not. Parameters are well covered by the schema, but the return-shape gap leaves the definition only minimally adequate.

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

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

Schema description coverage is 100%, so each of the 5 parameters is already documented (group_by, view_mode enum, timeframe bounds, subscription_id). The description adds no syntax, default, or interaction detail (e.g., how group_by and view_mode combine), 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 costs for a subscription over a timeframe'), so the agent knows exactly what it returns. It never names the closely related sibling orb_get_customer_costs, so the subscription-vs-customer distinction is left to inference even though it's the most likely confusion.

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 guidance, no prerequisites, and no comparison to orb_get_customer_costs or orb_get_subscription_usage, which are the obvious alternatives. Usage is only implied by the resource 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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lower. The description adds that the payload is specifically the plan-change schedule (and the REST path), but says nothing about pagination behavior, ordering, or emptiness semantic despite carrying limit/cursor params.

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

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

Two tight sentences with the purpose front-loaded and no wasted wording. The trailing API-path sentence is somewhat redundant with the name and title but is compact and harmless.

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, single-required-param tool with full schema coverage and no output schema, the description is nearly sufficient. It clarifies the schedule concept adequately; only the pagination context (limit/cursor use) is left entirely to the schema.

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

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

Schema description coverage is 100%, so subscription_id, limit (1–100, default 20) and cursor are fully documented in the schema itself. The description adds no parameter-level meaning beyond that, which is the expected baseline 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?

The description gives a specific verb ('Get') and a precise resource qualifier ('the plan-change schedule for a subscription'), which distinguishes it conceptually from siblings like orb_get_subscription and orb_get_subscription_usage. It does not, however, name any sibling explicitly, so an agent must infer the boundary itself.

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 by the resource name: read the plan-change schedule when you need to know upcoming plan changes. There is no explicit statement of when to prefer this over orb_get_subscription or orb_get_upcoming_invoice, and no exclusions or prerequisites 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?

readOnlyHint=true already declares a safe read, so the burden is lower. The description adds the REST mapping (GET /subscriptions/{subscription_id}/usage), which is mildly useful context but discloses nothing about pagination, bucket limits, defaults when granularity is omitted, 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 compact sentences, purpose front-loaded, no filler. The endpoint reference is the only marginal line, but it is short and the whole definition is well under any bloat threshold.

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 is the only place the return shape could be sketched (buckets, grouped rows, aggregation semantics), and it does not. For a 5-parameter, bucket-producing usage endpoint, the definition is adequate but leaves the agent guessing about what comes back.

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 are already documented in the schema (ISO-8601 bounds, inclusive/exclusive, group_by, granularity). The description only echoes the timeframe concept, adding no format or default detail beyond the schema – 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+resource ('Get metered usage for a subscription') plus the scope ('over a timeframe'), which separates it from cost-oriented siblings like orb_get_subscription_costs. It stops short of explicitly naming a sibling to disambiguate against, 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?

Usage is implied by the resource itself (get subscription usage), and the 'over a timeframe' phrase hints that the timeframe params are expected. However there is no explicit when-to-use, when-not, or alternative named – notably no distinction from orb_get_subscription_costs or orb_get_subscription.

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 context by marking the invoice as a draft/preview that is not yet final, which tells the agent the values may change. It does not cover permissions or whether a missing subscription errors.

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

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

Two tight sentences with zero filler, and the core purpose leads. The trailing API endpoint note is short and additive 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 one-parameter, read-only lookup with no output schema, the description supplies enough to call it correctly and correctly signals the result is a provisional draft. Minor gap: nothing about error behavior for an invalid or non-existent subscription 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?

Schema description coverage is 100% with a single well-documented parameter (subscription_id), so the schema does the heavy lifting. The description adds no format or constraint 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?

Specific verb ('Preview') plus a precisely scoped resource ('upcoming (draft) invoice for a subscription'), which cleanly separates it from the sibling orb_get_invoice (an issued invoice) and orb_list_invoices. It stops short of naming any sibling explicitly, so it earns 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?

The '(draft)' qualifier implies this is for seeing charges before they are finalized, but there is no explicit statement of when to reach for it over orb_get_invoice or orb_list_invoices, and no prerequisites or exclusions. Usage is inferable but not 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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It adds the HTTP endpoint mapping, which helps with debugging, but says nothing about pagination behavior, default page size, or result ordering that would go beyond the annotations and 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, purpose front-loaded, followed by the endpoint reference. No filler and nothing 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?

Without an output schema, the description could say more about what an alert record contains or how pagination terminates, but with 100% schema coverage, zero required params, and a readOnly annotation, the essential contract is conveyed.

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 limit, cursor, customer_id, subscription_id, and external_customer_id. The description restates the customer/subscription filtering idea but omits external_customer_id and the pagination parameters, adding no format or semantics 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 (usage/spend alerts) and even names the upstream endpoint (GET /alerts). No sibling in the toolset covers alerts, so there is zero ambiguity about which tool retrieves alert records.

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

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

The phrase 'optionally filtered by customer or subscription' implies when the filters would be applied, but there is no explicit guidance on when to use this versus, say, orb_get_customer_costs or orb_get_subscription_usage, and no statement of preconditions or 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?

readOnlyHint=true already tells the agent this is a safe read, so the burden is lower. The description adds the upstream endpoint (GET /coupons), which mildly corroborates read semantics, but says nothing about pagination behavior, default page size, or whether archived coupons are hidden 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?

Two short, front-loaded sentences with no padding. The endpoint reference is mildly redundant but costs little and confirms the underlying operation.

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

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

For a simple read-only list tool with fully documented parameters there is no output schema to explain, and the annotations cover the safety profile. However, nothing in the description addresses pagination mechanics (cursor/next page) or that coupons may be archived and hidden, which is the main behavioral nuance of this tool.

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

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

Schema description coverage is 100%, with limit, cursor, and show_archived each documented, including the 1–100 range and the origin of the cursor. The description adds no parameter 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+resource ('List coupons in the Orb account'), which cleanly separates it from the other list_* siblings (customers, invoices, plans, prices, subscriptions) by resource. It stops short of naming any alternative or scope constraint, so it is clear but not maximally distinguishing.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of how pagination or the archived flag should be used. Usage is only implied by the word 'List'.

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 description only adds the account-wide scope and the HTTP endpoint as corroboration. It says nothing about pagination behavior, default page size, or ordering — relevant for a list endpoint, though the cursor param hints at it.

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 no padding. The second sentence restates what the readOnlyHint annotation already implies, so it is mildly redundant rather than 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?

For a simple, fully-documented, zero-required-param list tool with safety annotations and no output schema, the description covers what is needed to invoke it. Only pagination/ordering behavior is left unstated.

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 both limit (1–100, default 20) and cursor are fully documented in the schema. The description adds no format or semantics beyond that, which is the correct baseline 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 ("List customers in the Orb account") and pins the underlying endpoint (GET /customers). The 'List' verb distinguishes it implicitly from read-one siblings like orb_get_customer and from the write sibling orb_create_customer, though it never names 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?

No guidance on when to use list vs get vs get_customer_by_external_id, no prerequisites, and no mention of pagination traversal strategy. 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, so the safety profile is covered. The description contributes only the REST endpoint path (GET /invoices), which adds no operational context such as pagination semantics, result ordering, or default limit behavior — all of which matter for a list 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 short sentences, front-loaded with the purpose; nothing is bloated. The trailing 'Orb API: GET /invoices' is largely decorative and could be dropped, keeping a clean 4.

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, the definition is minimally adequate. There is no output schema, and while pagination is documented via the cursor/limit parameters, the description never explains paging flow or default page size, leaving a modest 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 description coverage is 100%, so each of the 8 parameters (limit, cursor, status, due_date, date_type, customer_id, etc.) is already well documented in the schema. The description's mention of filters adds nothing 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?

States a specific verb and resource ('List invoices') plus the optional filter dimensions (customer, subscription, status). It is clearly distinguishable from the singular orb_get_invoice by verb, but it never explicitly contrasts itself with that sibling or explains list-vs-get behavior.

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 'optionally filtered by customer, subscription, or status' implies when this tool is useful (browsing/filtering a collection), but there is no statement of when NOT to use it or which sibling (e.g. orb_get_invoice for a single invoice) to prefer.

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 is a safe read. The description adds only the REST endpoint mapping (GET /items); it says nothing about pagination behavior, default page size, or result ordering, so it adds modest value rather than rich behavioral context.

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 action and resource. The endpoint restatement is marginally redundant but not harmful; 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?

For a paginated list tool with no output schema, the description omits cursor-based pagination flow and what the response contains. It is minimally adequate but leaves the agent to reconstruct pagination semantics from the schema alone.

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 (1-100, default 20) and cursor (opaque, from pagination_metadata.next_cursor) are fully documented in the schema itself. The description adds no parameter meaning beyond that, 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 ('List items') and clarifies the domain meaning of 'items' as 'the things you bill for', which disambiguates from generic items. It does not explicitly differentiate from sibling orb_get_item (single-item retrieval) or other list tools, 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?

No statement of when to use this tool versus orb_get_item or other list endpoints, and no prerequisites or context beyond the endpoint path. 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?

readOnlyHint=true already declares the read-only safety profile, so the description does not need to restate it. It adds only the REST endpoint mapping ('GET /metrics') and says nothing about pagination behavior at the call level, rate limits, or result ordering, so it adds modest value over 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?

Two short sentences, zero filler, with the core purpose front-loaded and the API endpoint mapping trailing. Nothing here needs to 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?

For a simple, annotation-covered, parameter-complete list tool, the description is nearly sufficient; no output schema exists but the cursor description implies paginated returns. It could note what the listing returns or max page size, 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% – both 'limit' (with range and default) and 'cursor' (with source of the value) are fully documented in the schema. The description adds no parameter-level detail, 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 resource ('billable metrics') with scope ('configured in the Orb account'), so an agent immediately knows what it retrieves. No sibling tool covers metrics, so differentiation is inherent, but the description never explicitly contrasts with the other orb_list_* tools, capping it below 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 enumeration semantics and the absence of a competing sibling, but there is no explicit when-to-use statement, no prerequisites, and no exclusions. It is the minimum viable level: an agent can infer the use case 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?

The annotations already declare readOnlyHint=true, and the description adds useful context by naming the API endpoint GET /plans and the account scope. However, it does not disclose auth requirements, rate limits, pagination behavior beyond the schema, 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 sentences, front-loaded with the purpose followed by the API endpoint. Every word earns its place with no filler.

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

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

This is a low-complexity read-only list tool; the schema fully documents all optional parameters and annotations cover the safety profile. The description gives purpose and endpoint, though it does not describe the return format and no output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents limit, cursor, and status completely. The description adds no additional parameter meaning, 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: 'List plans configured in the Orb account.' It clearly distinguishes this from the sibling orb_get_plan by indicating multiple plans rather than a single plan.

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

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

The description gives no explicit guidance on when to use this tool versus orb_get_plan or other list tools. There are no prerequisites, exclusions, or alternative-selection advice.

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 this is a safe, non-mutating read, so the description is not required to carry the safety burden. It adds only the endpoint identifier, and says nothing about result scope (all prices vs. active only), ordering, or pagination behavior beyond what the schema already 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 short, front-loaded sentences with zero filler. The purpose leads and the API reference is a compact secondary 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?

For a two-parameter, read-only list tool with complete schema coverage and no output schema, the description is minimally sufficient. It nonetheless omits any sense of what is returned (price types, active/inactive) or how pagination should be driven, which an agent coordinating multi-page listing would want.

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 limit and cursor fully documented in the schema including defaults and range. The description adds no additional parameter meaning, 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 resource (prices) scoped to the Orb account, and even cites the underlying endpoint GET /prices. It does not explicitly distinguish itself from the sibling orb_get_price, leaving the list-vs-single distinction to inference from the names.

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 mention of alternatives such as orb_get_price for a single price, and no prerequisites. The agent must infer that this is the bulk-retrieval variant 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the Orb API endpoint (GET /subscriptions), but does not elaborate on pagination, rate limits, or response behavior 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, front-loaded with the core action and followed by a useful endpoint reference. Every part earns its place.

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

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

For a read-only list tool with full parameter schema coverage and no output schema, the description is largely sufficient. It could mention pagination behavior, but the schema already covers limit and cursor semantics.

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 are fully documented in the schema. The description only mentions customer and status filtering, which adds marginal meaning beyond what the schema already explains.

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 clear verb+resource: 'List subscriptions.' It also names the available filter dimensions and the underlying Orb endpoint. However, it does not explicitly distinguish this tool from sibling list/get tools beyond the obvious plural naming.

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 says subscriptions can be optionally filtered by customer or status, which implies the main usage context. It does not say when to choose this over alternatives like orb_get_subscription or when not to use it.

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

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

Annotations already declare readOnlyHint=true, so the non-mutating nature is covered structurally. The description adds the auth-verification semantics ('verifies the API key works') and the underlying endpoint, which is useful context, but says nothing about response shape 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?

Two short fragments with no waste, purpose front-loaded, followed by the endpoint mapping. Nothing could be trimmed without losing information.

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

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

For a no-argument, read-only health check with no output schema, the description covers what is needed to invoke it. It could mention what success/failure indicates, but the gap is minor 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?

The tool takes no parameters and the schema is an empty object at 100% coverage, so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter tool.

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 purpose with verb and resource: 'verifies the API key works' plus 'health check', and pins it to GET /ping. It is trivially distinguishable from all sibling CRUD tools, though it doesn't explicitly say so.

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 — an agent infers this is the connectivity/credential smoke test — but there is no explicit when-to-use or when-not-to-use guidance, and no statement about what to do on failure.

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 supply the safety profile (destructiveHint=true), and the description adds genuinely useful behavior beyond that: partial-update semantics ('Only provided fields are changed'). However, the parenthetical '(reversible)' sits in tension with a destructiveHint of true and is not reconciled, so the signal is muddier than it should be. It also says nothing about auth scope or side effects of changing fields like email or payment_provider.

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, front-loaded clauses: what it does, the partial-update behavior, then the endpoint. No filler, no repetition of schema content.

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 9-parameter mutation tool with no output schema, the description covers the core mutation semantics and reversibility but omits what a caller gets back, permission/auth requirements, and any side effects of specific field changes. It is minimally sufficient rather than 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 every one of the 9 parameters is already documented (formats, enums, nested metadata constraints). The description's only parameter-relevant statement is that unspecified fields are untouched, which is close to what the single required field already implies. Baseline 3 is warranted 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?

The description gives a specific verb and resource ('Updates an existing customer's details') and the underlying endpoint (PUT /customers/{customer_id}), which pins down exactly what happens. The verb alone cleanly separates it from the create/get/list siblings in the toolset.

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 must infer that this is the tool for modifying an existing customer rather than orb_create_customer, and no explicit alternative or precondition is named. 'Only provided fields are changed' is the one piece of actionable usage context, telling the caller it can send a sparse payload.

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