orb

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

Annotation Contradiction: the description calls the operation 'additive', while the annotations mark destructiveHint true. This directly contradicts the annotation and sends conflicting signals about whether the tool may destroy data. No return format, error behavior, or side-effect context is provided.

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

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

The description is short and front-loaded, with the core purpose in the first clause. The repeated required-fields statement is somewhat redundant with the schema, but it is brief and does not harm clarity.

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 8-parameter creation tool with no output schema, the description offers only the basic purpose and required fields. It lacks return-value expectations, error behavior, and resolution for the conflicting destructiveHint annotation, leaving an agent under-informed about how to handle the call's result safely.

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 8 parameters. The description only repeats that name and email are required, adding no meaning beyond what the schema provides. The baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Creates') and resource ('new customer in Orb'), and adds the clarifying term 'additive' to indicate the operation's non-destructive nature. This is enough to distinguish it from the get/list siblings and from orb_update_customer.

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

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

The description provides prerequisites (name and valid email) but does not say when to use this tool versus alternatives. It does not mention that orb_update_customer should be used for existing customers or explain any uniqueness/idempotency concerns around external_customer_id.

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, covering the safety profile. The description adds the exact REST method (GET /customers/{customer_id}), which corroborates the read-only behavior. It does not describe not-found/error behavior or response shape, but for a simple read with annotations present, the added value is adequate but not rich.

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

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

Two sentences with zero waste: the action and identifier are front-loaded, and the API endpoint provides useful corroborating context. Every element earns its place.

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

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

For a single-parameter read operation with readOnlyHint=true and no output schema, the description supplies the essential facts: what it fetches, by which key, and via which endpoint. The only minor gap is unspecified behavior when the customer is not found, which is a small omission for an otherwise simple and well-covered tool.

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

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

Schema description coverage is 100%, so the schema already documents customer_id as 'Orb customer id.' The description's 'by Orb customer id' marginally adds meaning by contrasting with the external-id sibling lookup, but does not substantially exceed what the schema already states. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Fetch'), a distinct resource ('a single customer'), and the key identifier ('by Orb customer id'). This explicitly distinguishes it from siblings like orb_get_customer_by_external_id (different ID type), orb_list_customers (list vs single), and orb_create_customer/update_customer (mutations). The API endpoint reference reinforces the scope.

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

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

The phrase 'by Orb customer id' gives clear context for when to invoke this tool: when the agent holds an Orb-native customer ID. Given the sibling orb_get_customer_by_external_id, this implicitly differentiates the lookup key. However, it does not explicitly name alternatives or state when-not-to-use, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a read-only operation. The description adds only 'single customer' and the API path but does not disclose behavior for missing IDs, response format, or any other operational details. Adequate given the annotation coverage, but not rich.

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 succinct sentences, with the core purpose front-loaded and the API reference following. Every word contributes; there is no padding 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 single-parameter, read-only lookup tool with readOnlyHint set, the description is largely sufficient. It could mention what happens when the ID does not exist, and since there is no output schema, a hint at the return shape would help, but these are minor gaps for such a simple operation.

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 defines external_customer_id as 'Your external customer id.' The description repeats this without adding format, constraints, or usage examples, so it stays at the schema-covered baseline.

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

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

The description states a specific action ('Fetch a single customer') and resource ('by your external customer id'), clearly distinguishing it from orb_get_customer and orb_list_customers. The API endpoint further confirms the exact operation.

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

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

The description implies this tool should be used when the external customer id is available, and sibling names suggest orb_get_customer is for internal Orb IDs. However, it does not explicitly state when not to use this tool or name the alternative, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to establish the safety profile. It adds the timeframe scope and API endpoint but does not describe output shape, pagination, defaults, or how group_by and view_mode affect results. There is no contradiction, but behavioral detail is thin.

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

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

The description is very concise and front-loaded, with the core operation in the first sentence. The second sentence names the Orb API endpoint, which is useful reference but not essential for selecting or invoking the MCP 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?

The schema fully documents the parameters and the readOnly annotation covers safety, so a basic call can be made. However, with no output schema, the description does not explain what the returned cost data looks like, and it does not distinguish this from subscription-level costs, leaving moderate ambiguity.

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%: every parameter has a meaningful description, so the tool description does not need to compensate. The description adds no parameter details beyond the schema, so the high-coverage baseline of 3 applies.

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

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

The description states a specific verb and resource: get costs incurred by a customer, with a timeframe constraint. It is clear, but it does not explicitly distinguish itself from the sibling orb_get_subscription_costs, so it does not earn the top score.

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

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

There is no guidance on when to use this tool versus alternatives such as orb_get_subscription_costs or orb_get_customer_credits. The timeframe phrase is part of the operation, not a usage condition, and no exclusions or alternatives 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?

Annotations already declare readOnlyHint=true, so the read-only safety profile is covered. The description adds the 'by currency' scoping behavior and endpoint, but discloses no other behavioral traits such as default block filtering 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 with no filler; the core purpose is front-loaded and the endpoint line provides precise context. Every word 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 GET with full schema coverage this is mostly adequate, but the output format is not described (no output schema exists), and the distinction from the credits-ledger sibling is left implicit. Those are notable gaps for an agent deciding whether this call satisfies a credit-related request.

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

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

Schema coverage is 100% with clear descriptions for all three parameters, so the schema carries the parameter documentation burden. The description only paraphrases the currency dimension and adds no additional parameter meaning.

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

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

The description uses a specific verb and resource: 'Get a customer's credit balances by currency' and gives the exact Orb endpoint. It is clear, though it does not explicitly differentiate itself from the similarly named sibling orb_get_customer_credits_ledger.

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 is provided on when to use this tool over alternatives such as orb_get_customer_credits_ledger or orb_get_customer_costs. There are no use-case conditions, exclusions, or prerequisites.

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 the behavioral fact that the ledger is append-only. However, it does not explain pagination behavior, ordering, filtering side effects, or what the response contains, so behavioral transparency is only moderately developed.

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

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

The description is two concise sentences. The resource is stated immediately, the API endpoint is given for precision, and there is no filler or redundant elaboration.

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

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

The schema covers all parameters and the annotations cover read-only behavior, but there is no output schema and the description does not characterize the response shape or pagination metadata. It is adequate for a simple GET, but not fully complete.

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

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

The input schema documents all five parameters with descriptions, so the schema carries the parameter semantics. The description adds no further parameter-level meaning beyond restating the customer_id path, so the baseline score 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 clearly states the verb (Get) and the specific resource: the append-only credit ledger for a customer. It also provides the exact API path. It does not explicitly differentiate itself from the similarly named sibling orb_get_customer_credits, so sibling distinction 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 guidance about when to use this tool versus alternatives. Given the sibling orb_get_customer_credits, an agent might reasonably confuse the ledger endpoint with a credits summary endpoint, but the description does not clarify which situation calls for which tool.

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

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

The readOnlyHint annotation already tells the agent this is a safe read operation, and the description reinforces it with 'Fetch' and GET. The description adds the endpoint but no additional behavioral context such as 404 behavior, required auth scopes, or response format. Since annotations already cover 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?

Two short clauses: the purpose comes first ('Fetch a single invoice by id') and the API reference follows. No filler words, no redundant restatement of the tool name, and the essential information is front-loaded.

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

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

For a simple read-only tool with one required parameter and no output schema, the description plus endpoint is enough for an agent to make the call for a known invoice_id. It does not describe the return shape or error cases, but the tool's purpose and target resource are clear, so the remaining gaps are minor.

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% (invoice_id is described as 'Orb invoice id'). The description merely repeats the concept of 'by id' and shows it in the endpoint URL, adding no new meaning beyond what the schema already provides. Baseline 3 applies.

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

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

The description states a specific verb and resource: 'Fetch a single invoice by id.' and gives the exact API endpoint, which clearly distinguishes it from list-oriented tools like orb_list_invoices. However, it does not explicitly differentiate from the sibling orb_get_upcoming_invoice, nor does it name any alternative, so it stops short of a perfect 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 phrase 'by id' implies this tool should be used when the agent already has an invoice_id and needs one invoice. But the description gives no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives such as 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?

The readOnlyHint=true annotation already signals a safe read operation. The description adds the API endpoint and confirms the operation fetches a single item, which is consistent but not substantially beyond the annotation. No mention of 404 behavior, response format, or rate limits, but the annotation covers the main safety aspect.

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

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

The description is a single, efficient sentence with the API endpoint included. It is appropriately front-loaded and contains no fluff, though it could have added a bit more context without harming conciseness.

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-parameter read tool with a readOnlyHint annotation, the definition is mostly complete. However, it does not state what happens on a non-existent id, what fields the response contains, or how it differs from related list/get tools. Given the simplicity, this is adequate but not rich.

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%, as the item_id parameter has a description 'Orb item id.' The description adds minimal meaning beyond the schema, just restating that the item is fetched by id. Per rubric, baseline 3 applies when the schema already documents parameters.

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

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

The description clearly states 'Fetch a single item by id' with a specific verb and resource, and includes the API endpoint. However, it does not differentiate from sibling tools like orb_list_items or other get_* tools except by naming the item 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?

No guidance is given about when to use this tool versus alternatives such as orb_list_items or other retrieval tools. The context is implicit: use when you need a single item by id. There is no explicit exclusion or comparison to 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, so the read-only safety profile is established. The description adds the HTTP GET method and endpoint path, which is mildly useful context, but it does not disclose potential error behavior, return shape, or any rate-limit concerns. With annotations covering the safety dimension, this is adequate but not rich.

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 concise sentence states the action, resource, and API endpoint. There is no filler or redundant repetition; every phrase earns its place.

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

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

For a simple single-parameter read-only lookup, the description is largely complete. It does not describe the return payload, but the absence of an output schema and the simplicity of a get-by-id operation make this a minor gap rather than a critical omission.

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 'Orb plan id.' already documents the single parameter. The description reinforces that plan_id is used in the URL path via GET /plans/{plan_id}, adding slight extra meaning, but this does not significantly exceed what the schema already conveys.

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

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

The description states a specific verb ('Fetch'), a specific resource ('a single plan by id'), and the exact API endpoint. This clearly distinguishes it from sibling tools like orb_list_plans, which return multiple plans.

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 implies the tool should be used when the agent has a specific plan_id and needs a single plan. It does not explicitly contrast with orb_list_plans or state when not to use it, leaving the routing decision to inference from sibling names.

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 covers the safety profile, so the description does not need to restate that. It adds the HTTP GET endpoint, which is useful, but offers no additional behavioral context such as response shape, errors, or pagination. This is acceptable for a simple one-parameter read but not rich.

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

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

The description is extremely concise: two short sentences, with the core action front-loaded and the API route supplied as useful context. Every word 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 single-parameter read-only tool, this is complete: the purpose is stated, the parameter is fully documented in the schema, the read-only annotation is present, and the endpoint is given. Nothing material is missing for correct invocation.

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

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

The schema fully documents price_id as 'Orb price id.' with 100% coverage. The description adds no extra parameter-level meaning beyond what the schema and endpoint already convey, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Fetch'), a singular resource ('a single price'), and an identifier ('by id'), making the tool's purpose immediately clear. The API path GET /prices/{price_id} reinforces this and distinguishes it from list-oriented siblings like orb_list_prices.

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 clearly states the context: use this when you need one price by its id. It does not explicitly name alternatives or state when not to use it, but the 'single' qualifier and endpoint provide enough guidance for simple selection.

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

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

readOnlyHint=true already communicates this is a non-destructive read. The description adds the concrete API method and path, which helps an agent understand the exact underlying request. It does not cover error cases or response shape, but for a simple GET-by-id operation this is not a significant gap.

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

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

Two short sentences carry exactly the needed information: what the tool does and which API call it maps to. 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 single-parameter read-only fetch, the description plus schema is sufficient for an agent to invoke the tool correctly. There is no output schema, but 'Fetch a single subscription' implies the returned resource; explicit return-field documentation would be nice but is not essential here.

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 clearly documented as 'Orb subscription id.' The description's reference to '{subscription_id}' in the API path reiterates this without adding substantial new semantic detail, 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?

States a specific verb and resource: 'Fetch a single subscription by id', which clearly distinguishes it from orb_list_subscriptions. The explicit API endpoint 'GET /subscriptions/{subscription_id}' further reinforces the exact operation.

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

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

The description clearly indicates this is for fetching one subscription by its id, giving enough context to choose it over listing all subscriptions. It does not explicitly name alternatives or when not to use it, but the singular-by-id framing is unambiguous.

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 covers the safe read-only nature, and the description reinforces it by citing the GET endpoint. The description adds the timeframe concept but does not explain aggregation behavior, grouping effects, or timezone handling, so it adds only modest context beyond 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?

The description is two short, front-loaded sentences with no filler. The primary purpose comes first, and the API endpoint reference is useful supplementary context.

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

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

Given the 100% schema coverage, the readOnlyHint annotation, and the explicit endpoint, the description is largely complete for invoking the tool correctly. The main gap is the absence of any detail about the response shape, especially since there is no output schema, but the parameters and purpose are sufficiently clear.

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 documented in the schema itself. The description does not add any parameter-level meaning beyond what the schema already provides, so the baseline score 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 clearly states the operation: 'Get costs for a subscription over a timeframe,' naming both the resource (subscription) and the specific action (get costs). This distinguishes it from sibling tools like orb_get_subscription_usage and orb_get_customer_costs.

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 implies the tool is for fetching subscription cost data over a time range, but it gives no explicit guidance on when to prefer this over related tools such as orb_get_subscription_usage or orb_get_customer_costs. No alternatives or exclusions 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?

The annotations already provide readOnlyHint=true, so the safety profile is covered. The description adds the API endpoint and HTTP GET verb, which reinforces the read-only behavior but offers little additional context about pagination, edge cases, or response semantics. This is acceptable for a simple retrieval tool.

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

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

The description is two short sentences with no wasted words. The purpose is front-loaded, and the endpoint reference is a valuable addition without overexplanation.

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 tool with fully documented params and no output schema, the description provides enough information to select and invoke it correctly. It identifies the exact resource and endpoint, and the schema handles parameter details. It could mention response shape or pagination behavior, but the included context meets the needs of this straightforward 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?

The input schema describes all three parameters at 100% coverage, so the baseline is 3. The API path in the description adds useful meaning by showing that subscription_id is a path parameter, which goes slightly beyond the schema's flat property definitions.

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

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

The description clearly states a specific verb ('Get') and resource ('plan-change schedule for a subscription'), and includes the exact Orb API endpoint. This distinguishes it from sibling tools like orb_get_subscription and orb_get_subscription_usage without ambiguity.

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

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

The description gives a clear context: use this tool when you need the plan-change schedule for a specific subscription. It does not explicitly mention alternatives or exclusions, but the resource-specific language makes the intended use case obvious.

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 read-only nature is covered. The description adds the timeframe scoping and the Orb API endpoint, but it does not disclose return shape, pagination, or how grouping/granularity affect the result.

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

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

The description is a single sentence that front-loads the core operation and timeframe, with a compact API reference. There is no filler or repetition.

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

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

With no output schema and no usage-context guidance, the description leaves an agent uncertain about the response format and how group_by/granularity shape the returned data. The schema covers the parameters but not the full behavior needed for a multi-option usage query.

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 five parameters. The description adds little beyond implying timeframe_start/timeframe_end, which is not enough to raise the baseline score.

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

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

The description uses a clear verb and resource: it gets metered usage for a subscription over a timeframe. It is distinguishable from 'subscription' or 'subscription_costs' siblings by the word 'usage', but it never explicitly names the sibling tools or the differentiators, so it falls just 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?

The description gives no guidance on when to prefer this tool over close siblings like orb_get_subscription_costs or orb_get_subscription. There is no when-to-use, when-not-to-use, or alternative reference.

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 read-only nature is covered. The description adds the distinctive behavioral context that this is a draft/preview invoice rather than a finalized one, and it names the specific Orb API endpoint, going beyond what the 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?

The description is two short sentences with no wasted words. The primary purpose is front-loaded, and the API endpoint is a useful, non-redundant addition.

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-only tool with no output schema, the description sufficiently covers the purpose, the draft nature, and the API endpoint. There is little ambiguity about what the tool does and how to invoke 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% and the single parameter subscription_id is already well documented as 'Orb subscription id.' The description only restates the notion of a subscription without adding further detail about the parameter, so the baseline of 3 applies.

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

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

The description states a specific verb ('Preview') and resource ('upcoming (draft) invoice for a subscription'), and also gives the exact API endpoint. This clearly differentiates it from siblings like orb_get_invoice, which concerns finalized invoices, and orb_get_subscription, which gets subscription data rather than invoice data.

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 implies the tool is for previewing a draft invoice for a subscription, but it does not explicitly state when to use it over alternatives such as orb_get_invoice or orb_get_subscription. No exclusions or alternative routing are mentioned, leaving usage 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?

The annotations already declare readOnlyHint=true, and the description's 'GET /alerts' is consistent with that. It adds the API endpoint as a small extra behavioral clue, but does not disclose response shape, pagination defaults beyond the schema, or any rate-limit considerations.

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

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

The description is two short sentences with no wasted words. It front-loads the core action and filtering capability, then supplies the API reference as a useful confirmation.

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 operation, the description plus rich schema and readOnlyHint cover the essential call context. A return-format description would be helpful since there is no output schema, but the tool's simplicity keeps the gap minor.

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?

All five parameters already have detailed schema descriptions, so the baseline applies. The description's mention of filtering by customer or subscription is a useful summary but does not add meaning beyond the schema-provided parameter documentation.

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 exactly what the tool does: 'List usage/spend alerts' with optional filtering by customer or subscription. It also names the Orb API endpoint, reinforcing the resource. However, it does not explicitly contrast itself with sibling tools, though no sibling tool targets alerts.

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 implies its use case: fetch alerts, optionally narrowed by customer or subscription. It does not explicitly state when to prefer this over an alternative, but since it is the only alert-list sibling, the context is understandable.

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 read-only operation, and the description's 'GET /coupons' reinforces a non-mutating call. It does not describe the response envelope, default archived filtering, or rate limits, but the safety profile is adequately covered by 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?

The description is two short sentences with no filler, placing the purpose first and the API reference second. Every element contributes meaningfully without unnecessary elaboration.

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 operation with three optional, fully documented parameters and a readOnlyHint annotation, the description covers the essential invocation context. It does not spell out exact return fields, but no output schema is provided and the response is reasonably implied by 'List coupons' and the GET /coupons endpoint.

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

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

Schema description coverage is 100%, so limit, cursor, and show_archived are each fully documented in the input schema. The description adds no parameter-specific semantics, and with complete schema coverage the baseline of 3 applies.

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

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

The description uses a specific verb and resource, 'List coupons in the Orb account', and reinforces it with the exact Orb API endpoint, GET /coupons. This clearly distinguishes the tool from all sibling list tools by resource and makes its function immediately understandable.

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 account scope and explicit API endpoint clearly indicate this is the tool for enumerating coupons, and no alternative coupon-listing sibling exists to confuse it with. It does not explicitly state when not to use it, but for a resource-scoped list operation the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to restate read-only safety. It adds the API endpoint and account scope, but does not disclose additional behaviors such as response shape or pagination behavior beyond what the parameter schema already indicates.

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

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

The description is two short, purposeful sentences with no filler. The main action and scope are front-loaded, and the API endpoint is useful additional context.

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

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

For a simple, read-only listing tool with fully documented parameters and no output schema, the description is nearly sufficient. It clearly identifies what is returned at a high level, though it could explicitly mention the paginated list envelope for extra clarity.

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

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

The input schema covers both parameters completely, including min/max and default for limit and the meaning of cursor. The description adds no parameter-specific meaning, which is acceptable given the high schema coverage; baseline 3 applies.

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

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

The description uses an explicit verb-resource pair, 'List customers', and scopes it to the Orb account. It also cites the underlying API endpoint, making the intent unambiguous and distinguishable from sibling tools like orb_get_customer or orb_list_subscriptions.

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

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

The primary usage is clear: call this tool when you need to list customers. However, the description does not explicitly compare it with alternatives such as orb_get_customer or clarify when not to use it, leaving the guidance largely implied by the name and sibling set.

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 carried by structured data. The description adds the 'Orb API: GET /invoices' reference, which is consistent with read-only behavior and mildly informative, but it does not disclose pagination behavior, response shape, or rate limits. This is acceptable given the read-only annotation and simple list semantics.

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 operation and its filtering capability come first, and the API endpoint reference is a useful secondary detail. Every word 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 filtered-list tool with 8 fully documented optional parameters, a read-only annotation, and no output schema, the description is nearly sufficient. 'List invoices' implies a paginated collection as the return, and the cursor parameter references pagination_metadata. The only minor gap is that it doesn't state the default page size or confirm the list response shape, but the schema largely covers this.

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 input schema (limit/cursor for pagination, status/due_date/date_type for filtering, and the three id filters). The description's mention of 'customer, subscription, or status' mirrors schema properties without adding new meaning, 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') and enumerates the key optional filters (customer, subscription, status), so an agent can tell it apart from orb_get_invoice by resource and verb alone. It never names a sibling explicitly, so it stops just short of full differentiation, which is why it gets 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 phrase 'optionally filtered by customer, subscription, or status' gives clear context on how to narrow the listing, and the schema documents each filter. However, there is no when-to-use guidance versus alternatives like orb_get_invoice or orb_get_upcoming_invoice, and no exclusions are stated — usage must be inferred rather than stated.

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

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

Annotations already provide readOnlyHint=true, so safety is known. The description adds 'GET /items' (reinforcing read-only) and the domain clarification 'things you bill for,' but no additional behavioral context such as pagination behavior, auth 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?

A single compact sentence front-loads the action and resource; the parenthetical adds domain meaning without bloat. Appropriate length.

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 described optional params and clear sibling context, the description is nearly sufficient. It lacks any mention of return/pagination metadata, but the cursor schema references pagination_metadata, and the readOnlyHint covers side effects.

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%; both limit and cursor have descriptions including defaults, bounds, and cursor provenance. The tool description adds no parameter semantics, 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 'List items' with a clarifying parenthetical defining items as billing objects. It is clearly distinct from the singular orb_get_item sibling by verb/resource, though it does not name 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?

No conditions, prerequisites, or alternatives are mentioned. The description only states what the tool does, leaving the agent to infer when to prefer it over orb_get_item or other list tools.

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 communicates that this is a safe read operation, and the description adds the concrete API reference 'GET /metrics,' which is consistent with that. However, it does not disclose pagination behavior, API rate limits, or the shape of the returned data beyond what the schema implies.

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

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

The description is two short sentences with no filler. The primary action is front-loaded, and the API endpoint reference is compact and useful without duplicating schema 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 simple list operation with no required parameters, readOnlyHint, and fully documented pagination parameters, the description is nearly sufficient. The main gap is that it does not explain the expected response shape or pagination metadata, though this is a minor omission given the tool's low 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%, with limit and cursor both documented in the input schema. The description itself adds no parameter-level meaning, but because the schema fully covers the parameters, the baseline of 3 applies.

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

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

The description uses a specific verb and resource: 'List billable metrics configured in the Orb account.' This clearly identifies the operation and resource type, distinguishing it from other list_* siblings by name. It does not explicitly compare against a sibling tool, 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?

The description provides no guidance on when to use this tool versus the many orb_list_* alternatives, and no prerequisites or exclusions are mentioned. Selection is left entirely to the tool name and inferred intent, which is not enough for a tool in a large family of list tools.

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 the endpoint and account scoping but does not disclose pagination behavior, default status behavior, or response shape. No contradiction with annotations exists.

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

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

Two short sentences convey the operation, scope, and API endpoint without filler. Every word contributes useful information, and the description is appropriately front-loaded.

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

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

For a simple optional-parameter read-only list operation with fully documented parameters, this is nearly complete. It could be improved by stating the response shape or pagination behavior, but the cursor parameter and endpoint make it sufficiently usable.

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?

All three parameters (limit, cursor, status) are fully described in the input schema, so the schema carries the semantic burden. The description adds no additional parameter-level detail, which is acceptable here due to 100% schema coverage.

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

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

The description names the specific operation (List) and resource (plans), scopes it to the Orb account, and provides the exact endpoint. This clearly distinguishes it from orb_get_plan (single-plan lookup) and other orb_list_* siblings.

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

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

The description implies when to use this tool by saying 'List plans configured in the Orb account,' but it does not explicitly state when to prefer this over orb_get_plan or mention any alternatives/exclusions. Usage is inferable but not directly guided.

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

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

Annotations already declare readOnlyHint=true, and the description agrees. It adds the account scope and exact GET /prices endpoint, but no further behavioral detail such as pagination behavior or response shape is disclosed.

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

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

Two short, front-loaded sentences with no filler. The second sentence adds a concrete API reference rather than repeating 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 simple read-only list operation, the description plus schema and annotations cover the essential intent and parameters. It could mention that the result is a page of prices with pagination metadata, but the cursor parameter already implies this.

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 clear limit and cursor documentation. The description adds no parameter-specific meaning, so the baseline 3 for high schema coverage 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), resource (prices), and scope (configured in the Orb account). It is clearly distinct from orb_get_price and other orb_list_* siblings by naming the exact collection returned.

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

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

Provides no when-to-use guidance, prerequisites, or contrast with alternatives such as orb_get_price or orb_list_plans. The API endpoint reference is useful technical context but does not tell an agent when to choose this tool over 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?

The readOnlyHint annotation already indicates this is a safe read operation, so the description does not need to restate that. The description adds the API endpoint, which is mildly helpful, but it does not disclose pagination behavior, response shape, or any other behavioral nuance beyond what annotations and schema already convey.

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

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

The description is two short sentences with no filler. The core action is front-loaded, and the API reference is appended cleanly without disrupting readability.

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 operation, the description plus schema and annotations provide enough to select and call the tool: it lists subscriptions, supports optional filters, and the schema documents pagination parameters. The lack of an output schema means return details are somewhat implicit, but 'List subscriptions' sufficiently implies the response contains subscriptions.

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

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

Schema description coverage is 100%, so the parameters are fully documented in the input schema. The description's mention of filtering by customer or status aligns with the schema but adds no new semantic detail beyond what the parameter descriptions already provide.

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

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

The description clearly names the verb and resource: 'List subscriptions' and adds a useful detail about filtering by customer or status. It is distinct from the sibling orb_get_subscription by being a list operation, but it does not explicitly differentiate itself from any specific 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?

The phrase 'optionally filtered by customer or status' implies when the tool is useful, and the 'List' framing suggests use for collections rather than single subscriptions. However, there is no explicit guidance about when to choose this tool 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 provide readOnlyHint=true, and the description adds meaningful context beyond that: it confirms the operation is a connectivity/api-key validation and identifies the HTTP verb and endpoint. This gives the agent an accurate mental model with no contradiction.

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

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

Two sentences with zero waste: the first states the core purpose succinctly, and the second grounds it in the concrete API endpoint. It is appropriately front-loaded and every word contributes.

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

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

For a zero-parameter, read-only health check, this description is fully sufficient: it states the function, the endpoint, and the auth-checking behavior. No output schema is present, but nothing an agent needs to invoke the tool correctly is missing.

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

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

The tool takes zero parameters, so the empty schema is fully descriptive and no parameter documentation is needed. The description adds no parameter information, which is appropriate; baseline for zero-parameter tools is 4.

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

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

The description states a specific verb ('verifies') and resource ('the API key'), identifies the exact endpoint (GET /ping), and clearly distinguishes this health/auth check from all sibling tools, which are resource CRUD operations. There is no ambiguity about what the tool does.

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 makes the use case explicit: a health and auth check to verify the API key works. No sibling tool serves this purpose, so alternatives need not be named, and the scope is clear enough that an agent would not confuse it with the CRUD tools in the sibling 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?

The description says the update is '(reversible)', which directly contradicts the annotation destructiveHint: true. This is a serious inconsistency, and the description adds no other behavioral context beyond the partial-update note.

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

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

Two short sentences with no filler. The main behavior, reversibility caveat, partial-update rule, and API endpoint are all included efficiently.

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

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

Given the 9-parameter schema, partial-update semantics, and endpoint, the description is reasonably adequate. However, it does not mention what the tool returns, and the reversibility claim conflicts with the destructiveHint annotation, leaving some context unclear.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds the useful semantic that only provided fields are changed, but it does not add per-parameter meaning beyond the schema.

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

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

The description clearly states the operation: updating an existing customer's details, with partial-update semantics and the specific API endpoint. It distinguishes from create/get siblings via the word 'existing', but does not explicitly name alternatives or enumerate which details can be changed.

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 is given about when to use this tool versus orb_create_customer or orb_get_customer. The word 'existing' implies it is not for creation, but there is no explicit when/when-not or alternative-routing information.

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