Amberflo MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description adds the concrete consequence 'changes what the customer is billed' and the underlying API endpoint, which is useful beyond the hint. However it omits prerequisites, whether an existing plan is replaced or prorated, and any idempotency/permission behavior for a destructive write.

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

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

A single front-loaded sentence leading with 'WRITE:' plus a short API reference; every element earns its place and the mutation nature is visible at a glance.

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 destructive write with no output schema, the description covers purpose and impact but leaves prerequisite and side-effect questions (plan replacement semantics, effective-date defaults) unaddressed, so it is adequate 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 all five parameters (including the optional product_id and start/end times) are already documented in the schema. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb (assign/attach) and resource (pricing product plan to a customer) and immediately conveys the consequence: 'this changes what the customer is billed.' That distinguishes it clearly from the read-oriented siblings like amberflo_get_customer_plan and amberflo_list_customer_plan_history.

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 'WRITE:' prefix hints at the mutation context, but there is no explicit when-to-use guidance or routing to alternatives (e.g., 'use get_customer_plan to inspect the current assignment first'). Nothing tells the agent when this is the right tool versus other plan-related 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 'WRITE:' prefix plus the explicit note that it can also auto-create the customer in Stripe discloses both the mutation and an external side effect that annotations do not cover. It omits failure/duplicate-handling behavior (e.g., what happens if customer_id already exists) and any auth requirements, and the destructiveHint annotation is left unexplained for a create operation.

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 tight sentence with a compact parenthetical, front-loading the WRITE semantics and required inputs, then the optional Stripe side effect. 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?

With full schema coverage, no output schema needed, and the nested traits object documented in the schema, the description is nearly complete. Only duplicate/idempotency semantics and the odd destructiveHint annotation are left unaddressed.

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

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

Schema coverage is 100%, so each parameter (traits, enabled, email, create_in_stripe) is already documented in the schema. The description only restates required vs optional fields and adds no syntax or format detail beyond that, 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 ('WRITE: create/register a new customer in Amberflo') and even names the underlying endpoint (POST /customers/). This clearly distinguishes it from read siblings such as amberflo_get_customer and amberflo_list_customers.

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

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

It gives clear preconditions (customer_id and customer_name required, the rest optional) and notes the optional Stripe auto-creation path, which tells the agent when the extra behavior triggers. It does not name an alternative tool or spell out when not to use this one, so it stops short of full 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?

readOnlyHint=true already establishes this is a safe read, and the description usefully adds that the response is raw meter events rather than aggregates. It discloses nothing about pagination or the effect of take_limit on the event list, and gives no auth or rate-limit context for a tool that returns potentially large event sets.

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: the purpose and drill-down scope come first, the debugging use case second, and the endpoint mapping ('POST /usage/explain') closes it. 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 7-parameter tool with a nested filter object, an enum, and no output schema, the description covers intent and use case but says nothing about the shape or volume of returned raw events, which is the one thing an agent cannot recover from structured fields 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%, including per-parameter docs for meter_api_name, time range, filter, group_by, aggregation and take_limit, so the baseline is 3. The description adds no syntax, default, or interaction details (e.g. how aggregation interacts with raw event output) beyond what the schema already provides.

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

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

States a specific verb and resource: 'explain/drill into the raw meter events behind a meter's usage over a time range.' The emphasis on raw meter events implicitly distinguishes it from the aggregate siblings amberflo_get_usage and amberflo_get_all_usage, but those siblings are never named, so the 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?

'Useful to debug why a number looks off' gives a concrete trigger scenario for reaching for this tool rather than a plain usage query. It stops short of stating exclusions or naming the alternative tools (get_usage / get_all_usage) that an agent should use for aggregated numbers.

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 that grouping sends groupBy=customerId-ish behavior and that the range is optional-filterable, but says nothing about pagination, result volume, or the shape of 'total usage', which matters for a 5-parameter 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 compact sentences with the scope stated before the optional modifiers, no filler. The trailing 'API: GET /usage/all' is marginally useful for an agent that already has the tool schema, keeping it just short of a 5.

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

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

With no output schema, the description must carry the burden of explaining what comes back, and 'total usage' is left vague (per-bucket totals? summed? units?). The 100% schema coverage and readOnly annotation cover inputs and safety, so the gap is narrow but real for an aggregation 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 all five parameters, including defaults and the enum for time_grouping_interval, are already documented. The description restates the customer grouping/filtering semantics in prose but adds no syntax, default, or unit detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Get total usage across all meters') plus the scoping dimension (time range, grouped or filtered by customer), which distinguishes it from the single-meter amberflo_get_usage sibling. It never names that sibling explicitly, so an agent must infer the division of labor.

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

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

Usage is implied rather than stated: 'across all meters' suggests this is the aggregate alternative to amberflo_get_usage, and the optional grouping/filtering hints at when to use it. There is no explicit when-to-use/when-not statement, no mention of the sibling by name, and no 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /customers/?customerId=<id>), which is modest extra context, but says nothing about behavior when the customer does not exist (error vs empty) — the main unknown for this operation.

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 implementation detail. Nothing redundant, nothing 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 no output schema and readOnlyHint declared, the description supplies enough to invoke correctly. The only meaningful gap is not-found semantics, which 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?

Schema coverage is 100% and the single parameter is fully documented in the schema, so the baseline of 3 applies. The description restates that the argument is the Amberflo customerId but adds no format, casing, or example 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 (Fetch), resource (customer), and scope (a single customer by customerId) — the word 'single' implicitly separates it from amberflo_list_customers. It stops short of naming that sibling explicitly, so differentiation is inferential 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?

Usage is implied by 'a single customer by its customerId': use it when you already know the ID, otherwise use amberflo_list_customers. No explicit when-to-use or when-not guidance is given, so the agent must infer the routing.

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 the useful behavioral distinction that latest=true is the default and is ignored when a specific invoice is addressed, but says nothing about return format, error cases for non-existent invoices, or cache staleness 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?

A single sentence that front-loads the operation and then cleanly presents the two retrieval modes in parentheses, followed by the API path. 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 9-parameter read tool with no output schema, the description covers the core mode distinction well, but leaves the agent to infer the return shape, pagination, and error behavior. It is adequate but not rich, and the absence of an output schema shifts some burden onto the description that it does not carry.

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. The description reinforces the interaction between latest and the date fields, but adds no syntax or format detail beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Get a single customer invoice') and explicitly distinguishes the two retrieval modes: the current open invoice via latest=true vs. a specific past invoice via product_plan_id + year + month + day. It also names the underlying API path, and the singular 'single invoice' contrasts cleanly with the sibling amberflo_list_customer_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?

The description clearly names both usage modes and the parameters that select them, so an agent knows when to use latest vs. the date-addressed path. It does not, however, explicitly name amberflo_list_customer_invoices as the alternative for enumerating multiple invoices, leaving that inference to the agent.

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

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

readOnlyHint=true already declares this is a safe read, so the description only needs to add context. It usefully clarifies that only the LATEST assignment is returned (not the full history) and exposes the underlying REST endpoint, but says nothing about failure behavior when no plan is assigned or the shape 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 tight sentences: the purpose and the distinguishing 'LATEST' qualifier are front-loaded, and the endpoint follows as supporting detail. 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-only tool this is nearly sufficient, but with no output schema the description gives only '(pricing)' as an indication of what is returned and omits the no-plan-assigned edge case. An agent knows how to call it but not fully what to expect 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?

The single parameter has 100% schema description coverage ('The Amberflo customerId.'), so the schema carries the semantics. The description restates the query string form CustomerId=<id>, which adds a little transport detail but no new meaning beyond the schema.

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

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

States a specific verb and resource (get a customer's assigned product plan) and adds the qualifier 'LATEST', which meaningfully distinguishes it from the sibling amberflo_list_customer_plan_history. It stops short of naming the sibling explicitly, but an agent can infer the boundary.

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: 'LATEST' signals this is the current-plan lookup versus the history listing, but there is no explicit when-to-use statement, no mention of prerequisites (e.g. the customer must have a plan assigned), and no named alternative.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds only the underlying endpoint (POST /usage/) and the fact that results are aggregated and optionally grouped, but says nothing about pagination, result size limits, or how take_limit/take_is_ascending interact with grouping.

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 clauses with the core purpose front-loaded and no filler. The trailing 'API: POST /usage/' is low-value metadata for an agent choosing a tool, but it costs little.

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 tool with a nested filter object and no output schema, the description is adequate but thin: it doesn't characterize the aggregated response shape or the interaction between take_limit and group_by. Rich schema coverage compensates for the parameter gap, keeping this at minimum viable.

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, including defaults for end_time_in_seconds and the sort default for take_is_ascending. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description gives a specific verb+resource ('Query aggregated usage for a single meter') with scope ('over a time range, optionally grouped/filtered'), which implicitly separates it from the sibling amberflo_get_all_usage. It stops short of explicitly naming or contrasting with any sibling, so it lands at clear-but-undifferentiated.

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?

'for a single meter' implies the contrast with amberflo_get_all_usage and amberflo_explain_usage, but no alternative is named and no when/when-not condition is stated. Usage is implied rather than guided.

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

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

Annotations only supply destructiveHint=true; the description adds substantive context beyond that, noting it writes billable usage data and targets the Amberflo ingestion host via POST /ingest/. It stops short of disclosing idempotency/retry behavior, auth requirements, or rate limits, so it is good but not exhaustive.

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

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

Two front-loaded sentences with zero waste: the operation and write nature come first, then the transport detail. Every clause carries information an agent can act on.

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

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

For a 6-parameter write tool with no output schema and only a destructiveHint annotation, the description covers what the tool is, that it mutates billable data, and the endpoint. It leaves out operational concerns such as rate limits, duplicate-event handling, and required credentials, keeping it just shy of 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?

Schema description coverage is 100%, so all six parameters, including the nested dimensions object and optional unique_id, are already documented. The description adds no field-level 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 (record/ingest) and resource (a single usage meter event), plus the exact endpoint (POST /ingest/). The 'single' scope and the WRITE label cleanly separate it from the read-oriented siblings like get_usage, get_all_usage, and explain_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?

The 'WRITE:' prefix and 'record/ingest a single usage meter event' imply when to use it, but the description never names an alternative or states exclusions (e.g., batch vs single, when to prefer explain_usage). Usage is inferable rather than explicit.

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

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

readOnlyHint=true already establishes the safe-read profile, and the description adds the API route plus the notion that results are scoped to a customer/product. It does not disclose anything about the caching behavior (from_cache defaults to true), freshness of results, or ordering/pagination, which are the real behavioral unknowns for a list 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?

A single front-loaded sentence carries the substance, followed by a compact API path. Nothing is padded, though the trailing 'API: GET ...' line is metadata that contributes little to tool selection.

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?

A simple read-only list tool with fully documented parameters and a readOnly annotation needs little more. With no output schema, one would ideally know the return shape and ordering, but the omission is minor for this complexity level.

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 four parameters including defaults. The description only echoes the product and payment-status dimensions, adding no syntax, format, or default detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('List all invoices for a customer') and adds scope detail ('optionally for a specific product, with payment status'). It is distinguishable in practice from the singular sibling amberflo_get_customer_invoice, though that contrast is never made explicit.

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

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

The optional product scoping and payment-status mention imply when this tool fits, but there is no explicit when-to-use vs. when-not guidance and no pointer to the sibling amberflo_get_customer_invoice for single-invoice lookups. Usage is left to inference.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the API endpoint and the fact that it returns a full history over time, which is useful behavioral context, but it does not mention pagination, response format, or any limits on the returned history.

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 sentences with no wasted words, and the core purpose is front-loaded before the API endpoint 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 simple read-only list tool with one documented parameter and readOnlyHint coverage, the description provides enough context to invoke the tool correctly. It only lacks return-value details such as ordering or pagination, but no output schema exists and the core behavior is 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 the single customer_id parameter is already documented. The description adds the API query parameter spelling CustomerId=<id>, but does not add meaning beyond what the schema provides, matching the baseline for full schema coverage.

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

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

The description states a specific verb and resource: list the full history of product plans assigned to a customer over time. It clearly scopes the operation to historical data, which helps distinguish it from a current-plan tool, though it does not explicitly name the sibling it differs from.

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 'full history ... over time,' suggesting the tool is for retrieving historical assignments. However, it does not explicitly say when to use this versus the sibling get_customer_plan or other plan-related tools, so the agent must infer the selection criteria.

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, but the description adds the concrete endpoint (GET /customers/) and the shape of returned records, which is useful because no output schema exists. It omits any pagination or result-limit behavior, which matters for a 'list all' 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?

Three short sentences, front-loaded with the core purpose, followed by the field list and the usage hint. Every sentence carries distinct information, and 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?

With no output schema, the description compensates by listing the returned fields, and it supplies the endpoint and a discovery-oriented usage hint. The only real gap is the absence of pagination/ordering information for a potentially large listing.

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, so there is nothing for the description to clarify beyond what the empty schema shows; baseline 4 applies. The description does not invent or misstate any input semantics.

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 all customers') with explicit scope ('registered in your Amberflo account') and enumerates the returned fields (id, name, email, traits, enabled). The list-vs-single distinction makes it unambiguously separable from siblings like amberflo_get_customer or amberflo_create_customer.

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

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

'Good first call to discover customer ids' gives clear situational context for when to reach for this tool. It does not name alternatives or state exclusions (e.g., when to prefer get_customer for a known id), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds that the returned meterApiName values feed other usage tools, which is useful workflow context, but says nothing about pagination, result size, or auth requirements. Adds some value beyond annotations, hence a middle score.

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 lead with the scope and returned fields, followed by the downstream use case. The trailing 'API: GET /meters' is mildly redundant but conventional and costs little.

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

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

With no output schema, the description usefully names the returned fields and their downstream purpose, which is what an agent needs to consume the result. Missing details like pagination or total count keep it from being 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 tool takes zero parameters, so there is no parameter semantics to mis-explain; baseline 4 applies. The description instead documents the response fields, which the schema does not cover since there is no output schema.

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

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

States a specific verb and resource ('List all meter definitions in your account') and enumerates the fields returned (id, meterApiName, label, meterType, aggregation). The scope is unambiguous and clearly distinct from the usage-oriented 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?

Explains the downstream purpose — 'Use meterApiName values here as inputs to usage tools' — which tells the agent why and when to call this before usage tools. It stops short of naming a specific alternative tool or stating exclusions, so it is clear context rather than full 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?

readOnlyHint=true already tells the agent this is a safe read; the description's genuine addition is the word 'active', signaling that only active prepaid orders are returned rather than all orders. It omits pagination, ordering, and auth/scope behavior, so it adds some value but not 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 tight sentences with the purpose front-loaded; the raw endpoint string is somewhat redundant restatement rather than new information, but nothing is bloated or buried.

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

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

For a simple two-parameter read-only list tool with full schema coverage and a readOnlyHint annotation, the description covers purpose and scope adequately; no output schema exists so return-value explanation is not required.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including the product_id default of "1". The description restates the param names in the URL example but adds no syntax or semantics beyond the schema, matching the baseline of 3.

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

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

States a specific verb (List) and a precise resource (a customer's active prepaid credit orders for a product), including the qualifying scope 'active'. The resource is unique enough among the siblings that an agent can distinguish it without opening the schema, though it never explicitly contrasts with any sibling.

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

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

Usage is only implied by the resource description: an agent infers it should call this when it needs a customer's prepaid orders. There is no explicit when-to-use, when-not-to-use, or named alternative, though no sibling tool competes for this task.

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