Lago MCP by usefulapi

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

The readOnlyHint annotation already covers the safety profile, so the bar is lower. The description does add real value by disclosing the revenue formula (advance fees included, tax/discounts deducted), but says nothing about return granularity, time zone, or pagination behavior for a multi-month window.

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 metric definition front-loaded and the API route appended. Nothing is wasted or repeated from the title.

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

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

For a read-only analytics endpoint with a fully described schema and no output schema, the description supplies the key missing piece, what the number means, and is nearly complete. Minor gaps remain on return shape and default time window, but an agent can call this correctly.

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

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

Schema description coverage is 100%, so months, currency, and external_customer_id are each documented in the schema, which is the baseline expectation. The description adds no syntax, default, or interaction detail beyond the schema.

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

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

Names a specific metric (gross revenue) and defines exactly what it comprises: finalized invoice payments plus advance fees, net of tax and discounts, plus the underlying API route. This clearly separates it from the sibling lago_analytics_mrr, though it does not explicitly call out that distinction.

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

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

No statement of when to use this versus lago_analytics_mrr or the other analytics/list tools, and no note on prerequisites such as which currency or customer scope must be set. The agent has to infer usage entirely from the metric name.

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

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

The readOnlyHint annotation already declares this is a safe read. The description adds that the figure is sourced 'from subscription fees' and names the underlying endpoint, which is mild extra context, but says nothing about return granularity, aggregation, or defaults when parameters are omitted.

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 fragments with no filler. The 'Lago API: GET /analytics/mrr' line adds little beyond what the name and purpose already convey, but total size is small and efficient.

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

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

There is no output schema, so the description carries more of the burden for describing what comes back, yet it does not sketch the response shape (e.g. per-month or per-currency series). For a two-param analytics read, it is adequate but has a visible gap.

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

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

Schema description coverage is 100%, so both parameters (months, currency) are fully documented in the schema. The description adds no format or semantic detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource and defines the acronym: 'Monthly recurring revenue (MRR) from subscription fees.' An agent can tell it retrieves an MRR metric. It does not explicitly differentiate itself from the similarly-named sibling lago_analytics_gross_revenue, leaving the choice 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?

No when-to-use or when-not guidance. The obvious alternative, lago_analytics_gross_revenue, is never mentioned, nor is any condition that selects one metric over the other. Only the implied 'get analytics' framing is present.

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 explicitly labels the operation '(additive)', which is the MCP-spec wording for destructiveHint=false, while the annotations declare destructiveHint=true. Key behaviors are also undisclosed: what happens if the external_id already exists (upsert vs. error), whether the call overwrites existing customer fields, and whether permissions beyond the API key are needed.

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

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

Two compact sentences, front-loaded with the verb+resource and followed by the single most useful implementation detail (endpoint and body envelope). Nothing extraneous.

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

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

For a create tool with no output schema, the description adequately covers what is created but omits the duplicate-external_id/upsert behavior, the return payload, and any auth or rate-limit expectations. The schema is rich enough that missing parameter detail is acceptable, but the behavioral gaps leave an agent guessing at edge cases.

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

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

Schema description coverage is 100% across all 12 parameters, so the schema already carries the field semantics and the baseline of 3 applies. The description adds only the outer body shape ('{ "customer": { ... } }'), a small formatting hint rather than per-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?

States a specific verb and resource ('Creates a customer in Lago') and adds the underlying endpoint (POST /customers) plus the body envelope, so the agent can tell exactly what operation this performs. No sibling performs a customer creation, so it is inherently distinct from lago_get_customer and lago_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?

The description never says when to reach for this tool versus alternatives (lago_get_customer, lago_list_customers) and gives no prerequisite or precondition guidance. The lone qualifier '(additive)' gestures at semantics but is not usage direction.

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

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

Annotations only declare destructiveHint=true; the description adds real behavioral context beyond that — that the event is billed, and crucially that it is idempotent via transaction_id, which governs safe retries. It stops short of auth/rate-limit details but covers the key operational traits.

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

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

Three short sentences, front-loaded with the verb and the billing impact, followed by idempotency. The API endpoint/body note is marginally redundant but harmless; overall tight and well-ordered.

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 mutation tool with no output schema and full schema coverage, the description supplies the missing operational context: billing impact and idempotency. Only auth requirements and response expectations are unaddressed, which is acceptable 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%, so all six parameters are already documented, including the transaction_id idempotency key. The description adds nothing parameter-specific beyond what the schema provides, 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 ('Records') and resource ('usage/metering event in Lago'), and the concept is unambiguous. It is trivially distinguishable from the read/list/analytics siblings, so no confusion is possible.

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 effect clear (counted toward usage, affects billing) which helps decide whether to call it, but it offers no explicit when-to-use guidance or exclusions. With no competing sibling, the usage is implied rather than stated.

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

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

The readOnlyHint=true annotation already establishes this is a safe read, but the description adds no behavioral context beyond that: no 404 handling for an unknown code, no pagination/rate-limit notes, and nothing about what is returned. It essentially only restates the REST route.

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, the purpose is front-loaded, and the API route is appended as supporting detail. Nothing is wasted 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 one-parameter read tool with an annotation covering safety and no output schema, the definition is minimally adequate. It could still note failure behavior for an invalid code or briefly characterize the returned metric object.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents 'code' as the unique code. The description's 'by code' merely echoes the schema, which is the baseline 3 case.

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

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

States a specific verb+resource ('Retrieve a single billable metric') and scopes it to one record via 'single' and 'by code', which distinguishes it from the sibling lago_list_billable_metrics. It does not name that sibling explicitly, so it falls just short of 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 code' implies you need a code in hand, so usage is inferable, but there is no explicit when-to-use statement, no mention of the alternative list tool, and no guidance on what to do if the code is unknown.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds only the underlying API route (GET /credit_notes/{lago_id}), which gives no behavioral detail such as what a missing id returns or whether the response is cached/paginated.

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 operation and resource, with the API route as a compact secondary reference. 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?

There is no output schema, so the description is the only place the return shape could be described, and it says nothing about what a credit note object contains. For a trivial single-resource getter with read-only annotations and complete parameter docs, this is adequate but noticeably thin.

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 a single required parameter already documented as a UUID in the schema, so the description need not add anything. Its mention of 'Lago id' merely echoes the schema, matching the baseline for fully-covered parameters.

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

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

States a specific verb ('Retrieve') and resource ('a single credit note') identified by Lago id, which cleanly separates it from the list-style sibling lago_list_credit_notes. It stops short of naming that sibling explicitly, so it misses the top band.

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

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

The phrase 'by its Lago id' implies the precondition (you must already have an id), but there is no explicit when-to-use guidance, no statement of when to prefer the list tool instead, and no error/not-found guidance. Usage is inferable but not stated.

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

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

readOnlyHint=true already declares this as a non-destructive read, so the safety profile is covered. The description adds the underlying REST route, but says nothing about 404 behavior for unknown ids, error shape, or what the response contains. With annotations carrying the safety burden, this is adequate but 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?

Two short sentences, front-loaded with the operation and the key to use. The API route line is compact and helps confirm the exact resource being fetched; nothing is padded or repeated.

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

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

For a one-parameter read with rich annotations this is close to sufficient, but with no output schema the description never hints at the returned customer fields or what happens on a missing id. A brief note on the response or error case would close the gap.

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

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

Schema description coverage is 100% and the single parameter is documented as "the customer external unique identifier (from your application)". The description repeats "by external id" but adds no format, casing, or example-value detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Retrieve a single customer") and pins the lookup key ("by external id"), which implicitly separates it from lago_list_customers and the usage/portal siblings. It stops short of naming the sibling explicitly, so an agent must infer the single-vs-list distinction.

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

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

Usage is implied by "single customer by external id" – an agent can reasonably infer this is the direct-lookup path versus lago_list_customers. However, there is no explicit when-to-use guidance, no prerequisites, and no named alternative as in stronger definitions.

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, and the description adds the temporal scoping ('current period'). It says nothing about permissions, whether data is real-time or cached, or the shape of the response, so it adds only modest value 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?

Two tight sentences with the purpose front-loaded and the endpoint reference appended usefully. No filler, though the endpoint restates callable information the agent already has via the name.

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

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

For a read-only tool with fully documented parameters and no output schema, the definition covers what is needed to call it correctly. The only omission is explicit differentiation from the sibling past-usage 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 three parameters carry their own documentation, establishing the baseline of 3. The description adds no extra meaning about the required subscription ID or the apply_taxes flag beyond what the schema already states.

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

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

States a specific verb (retrieve), resource (usage-based billing data), and scope (current period), plus the underlying API endpoint. It implicitly distinguishes itself from lago_get_customer_past_usage via 'current period', but never names that sibling, so a 4 rather than a 5.

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

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

The phrase 'for the current period' implies the usage context versus past usage, but there is no explicit when-to-use/when-not guidance or named alternative. Adequate but leaves the agent to infer the routing against lago_get_customer_past_usage.

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 as a safe read, so the description is not the primary behavioral source. It adds no incremental context such as whether results require an active subscription, how many periods are returned by default, or pagination behavior, so it contributes little beyond the annotation.

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

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

Two short, front-loaded sentences with zero filler; the purpose leads and the API endpoint mapping follows compactly.

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 retrieval tool with full schema documentation and no output schema, the essential 'what it returns and for which scope' is covered; nothing required to call it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters (including the two required identifiers, periods_count, and billable_metric_code) are already documented in the schema. The description adds no syntax, format, or default-value guidance beyond that 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?

States a specific verb and resource ('Retrieve a customer's usage-based billing data') scoped to past periods, and even maps it to the underlying API endpoint. The 'past periods' scope implicitly distinguishes it from the sibling lago_get_customer_current_usage, though that sibling is never named.

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

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

Usage is implied rather than stated: an agent can infer this is for historical usage vs. lago_get_customer_current_usage, but the description gives no explicit when-to-use, when-not-to-use, or prerequisite guidance.

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

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

The readOnlyHint annotation already establishes this is a safe read operation. The description adds that the returned value is a billing portal URL and maps it to the REST endpoint, which is useful since there is no output schema, but it doesn't mention auth, expiry, or whether the URL is idempotent or generated per 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, front-loaded with the purpose, followed by the API mapping. Zero 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 tool with annotations covering the safety profile, the description is nearly complete. The main residual gap is absence of any hint about what the returned URL contains or how long it remains valid, which matters given there is no output schema.

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

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

Schema description coverage is 100% with only one required parameter, so the schema already documents external_customer_id fully. The path template restates the parameter but adds no format or semantic detail beyond it, making the baseline 3 appropriate.

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

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

States a specific verb (Get) and resource (customer's billing portal URL), which is clearly distinct from siblings like lago_get_customer or lago_get_invoice. However, it does not explicitly name which sibling it differs from or how, leaving differentiation 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?

Usage is only implied — an agent can guess this is for generating a portal link for a customer, but there is no when-to-use vs. when-not, no mention of prerequisites, and no reference to alternatives such as lago_get_customer.

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, and the description is consistent with that ('Retrieve'). It adds the underlying API route (GET /invoices/{lago_id}) but says nothing about error behavior for an unknown id or what the returned object contains.

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

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

Two short, front-loaded sentences with no waste; the identifier and the endpoint mapping are the only information present, and both earn their 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 one-parameter read tool with readOnlyHint coverage, the definition is nearly sufficient to invoke correctly. Without an output schema, a brief note on what the invoice object returns would have closed the remaining gap.

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

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

Schema description coverage is 100% and the single parameter lago_id is already documented as a UUID in the schema, so the description's 'by its Lago id' adds no semantics beyond it. 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 (Retrieve) and resource (a single invoice) keyed by Lago id, which implicitly separates it from the sibling lago_list_invoices. It stops short of naming the alternative explicitly, so the distinction must be inferred from the word 'single'.

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

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

There is no when-to-use guidance and no mention of the sibling lago_list_invoices as the alternative for bulk retrieval. The only signal is 'single invoice' in the purpose sentence, which is implied rather than stated as a selection rule.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the description's addition of the raw endpoint is minor context. It does not disclose what happens when the code does not exist or what shape the response takes, which is the remaining behavioral 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 terse sentences with the core action front-loaded and the endpoint reference appended; nothing is wasted and the key constraint comes first.

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

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

For a single-parameter read tool with annotations carrying the safety profile and no output schema, this is essentially sufficient. Slightly more could be said about the not-found case, but nothing essential for calling it correctly is missing.

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

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

Schema description coverage is 100% and the sole 'code' parameter is documented as 'The plan's unique code.' The description's 'by code' only restates that, adding no format, casing, or lookup semantics beyond the schema.

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

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

States a specific verb (Retrieve) and resource (a single plan) scoped by code, and adds the concrete API mapping GET /plans/{code}. It implicitly contrasts with lago_list_plans via 'a single plan', but never names the sibling, so the differentiation is inferential rather than explicit.

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

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

The 'by code' phrasing implies you use this when you already know the plan's identifier, which is useful context, but there is no explicit when-to-use versus lago_list_plans or any statement about prerequisites or failure behavior.

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 only the underlying REST endpoint (GET /subscriptions/{external_id}), which is documentation mapping rather than behavioral context such as error behavior or auth/permission requirements. With annotations present, 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 sentences, front-loaded with the operation and lookup key. Nothing is bloated; the endpoint sentence is slightly redundant but serves as a useful API mapping.

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

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

This is a low-complexity single-object GET with full schema coverage and a readOnly annotation. No output schema exists, so the description could say more about the returned subscription, but the tool's purpose and required input are unambiguous enough 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?

Schema description coverage is 100% and the single parameter is already documented as the subscription's external unique identifier. The description merely restates 'by external id' with no added format, sourcing, or validity guidance, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Retrieve a single subscription by external id.' The word 'single' implicitly distinguishes it from the sibling lago_list_subscriptions, but no sibling is named. An agent can identify the operation, though 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?

No when-to-use guidance, no alternatives, no prerequisites. 'By external id' hints at the required lookup key but the description never says to prefer this over lago_list_subscriptions or lago_list_customer_subscriptions, nor what to do if the subscription is not found.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds that results are paginated and maps to GET /add_ons, which is useful context, but it says nothing about ordering, default page size, 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 zero filler and the purpose front-loaded. The API endpoint note is compact and earns its place as a reference, though it is slightly redundant with the tool name.

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

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

For a simple read-only, zero-required-parameter list tool with no output schema, the description covers the essentials, but it leaves the agent without any sense of what an add-on record contains or how results are ordered. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so both page and per_page are fully documented in the schema itself. The word 'paginated' in the description only indirectly signals those parameters, adding no syntax or default-value 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 (List) and resource (add-ons) and notes pagination, which is enough to distinguish it from sibling list tools like lago_list_coupons or lago_list_plans. It does not explicitly differentiate from those siblings, but the resource name 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 gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. Pagination is mentioned but not framed as a usage condition (e.g., when to iterate pages or how to size per_page).

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 only the pagination nature and the underlying REST endpoint, without noting default page size, whether all records are returned, or rate limits.

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

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

Two short sentences, front-loaded with the core action and no filler. The endpoint reference is mildly redundant but harmless and compact.

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 paginated list tool with 100% schema coverage and no required parameters, the description is sufficient; no output schema exists, so return values need not be described. Minor gap: default paging behavior is unstated.

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

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

Schema description coverage is 100%, so both 'page' and 'per_page' are already documented in the schema. The description adds nothing beyond the generic word 'paginated', which is the expected baseline when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('List billable metrics') plus a scope qualifier ('paginated'), so the agent knows exactly what it returns. It does not, however, distinguish itself from the sibling lago_get_billable_metric or explain why one would list rather than fetch a single metric.

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

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

There is no explicit when-to-use guidance, no mention of alternatives such as lago_get_billable_metric for a single record, and no stated prerequisites. Usage is only weakly implied by the word 'List'.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds only that results are paginated, which is modest but useful context beyond the annotation. No return shape, ordering, or filtering behavior 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 sentences, front-loaded with the core action and zero filler. 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 simple read-only list tool with only two pagination parameters and no output schema, the description covers the essentials. It could note default page size or ordering, but nothing critical is missing.

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

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

Schema description coverage is 100%, with both 'page' and 'per_page' fully documented in the schema. The description adds nothing beyond the schema's own pagination 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 and resource ('List coupons') with the underlying endpoint, so the action is unambiguous. It does not explicitly differentiate itself from sibling list tools like lago_list_plans or lago_list_add_ons, though the resource name is distinct enough to infer.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of filtering or scope. The agent must infer usage purely from the resource name.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds the API endpoint reference but no pagination behavior, ordering, or result-set characteristics beyond the read-only signal.

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

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

Two short sentences with the filter constraint front-loaded; no wasted words. The endpoint citation is marginal but harmless.

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

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

Adequate for a simple list tool with readOnlyHint and full schema coverage, but it omits pagination defaults and result shape, and does not differentiate from the single-get sibling.

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 three params are documented in the schema. The description only reinforces the customer filter, adding nothing 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 clear verb+resource ('List credit notes') and adds the customer-filter capability. It does distinguish scope from the sibling lago_get_credit_note (single) vs this list tool, though without naming it explicitly.

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

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

The phrase 'optionally filtered by customer' implies when the external_customer_id filter applies, but there is no explicit when-to-use vs lago_get_credit_note guidance or when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds only that results are 'paginated', which is useful but thin — it says nothing about page size defaults, ordering, filtering options, or rate limits behavior. With annotations carrying the read-only signal, 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?

Two short sentences with the operation front-loaded and no wasted prose. The trailing 'Lago API: GET /customers' is mildly redundant with the first sentence but is a reasonable technical anchor rather than padding.

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

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

For a zero-required-parameter collection list with full schema coverage, no output schema, and a readOnlyHint, the description covers what is needed to invoke it correctly. Only marginal gaps remain around default ordering and result shape, which are not strictly necessary to make the call.

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 both parameters (page, per_page) are documented in the schema itself. The description's mention of 'paginated' corroborates but adds no syntax, defaults, or bounds beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List customers in Lago') plus the underlying endpoint 'GET /customers', so the operation is unambiguous. It does imply the plural collection scope versus the singular lago_get_customer sibling, but never names that distinction explicitly.

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

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

Usage is only implied by the verb 'List' — the agent can infer this enumerates all customers rather than fetching one. There is no explicit statement about when to prefer this over lago_get_customer, lago_list_customer_subscriptions, or the analytics tools, and no conditions or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the underlying HTTP method and path, which signals a simple scoped read, but says nothing about pagination, result limits, or whether inactive/canceled subscriptions are included.

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

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

Two short sentences with the purpose front-loaded and the API mapping secondary. No filler, though it is quite terse for a list operation.

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

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

Adequate for a one-parameter read with annotations covering safety, but on a list endpoint the absence of any note on pagination or result scope leaves a minor gap. No output schema exists, so return-shape information would have helped.

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

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

Only one parameter and schema coverage is 100%, so the schema fully documents external_customer_id. The description adds no format or semantics beyond what the schema 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?

States a clear verb (List) and resource (a customer's subscriptions), and the API endpoint reinforces the exact scope. It does not explicitly differentiate from the close sibling lago_get_subscription (singular) or lago_list_subscriptions (all subscriptions), but the 'a customer's' qualifier does most of that work.

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

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

No guidance on when to use this versus lago_get_subscription for a single subscription or lago_list_subscriptions for the full list. The API mapping implies read-only retrieval but no conditions or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered by structured data. The description adds the underlying endpoint (GET /fees) and the optional-filter nature, but says nothing about pagination behavior, result ordering, or volume/rate considerations for a list endpoint.

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

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

Two short sentences, front-loaded with purpose and followed by the filtering scope; the endpoint reference is a minor but useful addition. Nothing is wasted, though it is close to the minimum viable 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 five-parameter, zero-required list tool with a fully documented schema and no output schema, the description covers purpose and filters adequately. It is thin on pagination semantics and does not explain what a fee record contains, which an agent may need for follow-up reasoning.

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

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

Schema description coverage is 100% and all five parameters are individually documented in the schema, so baseline is 3. The description echoes the filter dimensions (customer/subscription/fee type) but adds no syntax, format, or default detail 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+resource ('List fees') and enumerates the filterable dimensions (customer, subscription, fee type), so the agent knows exactly what the tool returns. It does not explicitly differentiate itself from other list_* siblings, but the resource name 'fees' 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 word 'optionally filtered by' implies a valid usage context, and the API endpoint gives orientation, but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as a per-invoice or per-subscription fee endpoint.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description is not carrying the safety burden. It adds the underlying endpoint (GET /invoices), but says nothing about pagination behavior or result ordering, which would be genuinely useful for a 7-param 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?

Two tight sentences, front-loaded with the action and filters, with the API endpoint appended as useful routing context. No filler, though the endpoint clause is the only marginally optional element.

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

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

For a simple read-only list tool with full schema coverage and an annotation covering safety, no output schema is strictly needed and nothing essential is missing. A note on pagination or default page size would round it out.

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 each of the 7 parameters documented (status enums, date formats, external_customer_id). The description merely echoes those filter categories, adding no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('List invoices') with the filterable dimensions called out, so an agent knows exactly what it retrieves. It does not explicitly distinguish itself from the sibling lago_get_invoice (singular), but the list-vs-get distinction 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 phrase 'optionally filtered by...' implies the retrieval context and enumerates usable filters, giving implied guidance on when this tool applies. However, there is no explicit when-to-use vs when-not, and no pointer to lago_get_invoice for single-record lookups.

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

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

The annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the pagination trait and the underlying endpoint, which is modest additional context but says nothing about return shape, ordering, or defaults.

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

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

Two short sentences with the operation front-loaded and no filler. The 'Lago API: GET /plans' line is arguably redundant for an agent but is compact and not detrimental.

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 full schema coverage and readOnly annotations, little is left unspecified. The lack of any note on return format is acceptable given the tool's simplicity and the absence of an output schema.

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

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

Schema description coverage is 100%, so page and per_page are already documented in the schema. The description's 'paginated' nod confirms intent but adds no format, default, or boundary detail beyond what the schema 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?

States a specific verb (List) and resource (billing plans), and the 'paginated' qualifier clarifies the operation scope. It implicitly distinguishes from lago_get_plan by the plural listing verb, but never names the sibling to reinforce the distinction.

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

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

The intent is implied by 'List billing plans,' so an agent can infer this is the enumerate-all operation. However, there is no explicit when-to-use guidance, no mention of alternatives like lago_get_plan for a single plan, and no excluded cases.

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 /subscriptions), which is mildly useful, but says nothing about pagination behavior, result volume, or default filtering (status defaults to 'active'), which the schema hints at but is worth surfacing.

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

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

Two short clauses, front-loaded with the operation and filters, followed by the endpoint. Nearly zero waste, though the endpoint tagline is marginal value.

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

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

For a five-parameter filtered list with no output schema, the description is adequate but thin: it omits pagination defaults, the 'active' status default, and any routing against the near-identical sibling tool. Nothing is misleading, but an agent still has open questions.

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 already carry their own descriptions. The description restates the filter dimensions (customer, plan, status) but adds no format or default detail beyond the schema, so the baseline 3 applies.

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

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

Clear verb+resource: lists subscriptions with optional filters. It uses 'subscriptions' consistently with the name. However it does not differentiate itself from the sibling lago_list_customer_subscriptions, which is clearly a narrower read of the same 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?

The description implies when the tool is used (browse all subscriptions with optional filters) but gives no explicit when/when-not guidance or named alternatives, despite a very close sibling (lago_list_customer_subscriptions) that an agent would need help choosing between.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's added value is limited to the underlying API route. It does not disclose pagination behavior, what a wallet object contains, or whether wallets can be empty/multi-currency. With annotations covering the safety profile, this is an adequate but not rich disclosure.

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

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

Two sentences, zero filler, and the core purpose is front-loaded before the endpoint detail. Nothing could be trimmed without losing information.

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

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

There is no output schema, so the description carries some burden for describing what is returned, and it only names the entity type without saying what a wallet holds or that results are paginated. For a simple read-only list tool it is minimally sufficient, but it leaves the agent guessing about response shape.

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

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

Schema description coverage is 100% and all three parameters (page, per_page, external_customer_id) are documented in the schema itself. The description adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List), a specific resource (prepaid credit wallets), and the scope (a customer's), which cleanly separates it from siblings like lago_list_customers or lago_list_customer_subscriptions. The API endpoint mapping (GET /customers/{external_customer_id}/wallets) reinforces exactly what is retrieved.

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 when-to-use guidance, no prerequisites, and no alternatives. It never says to call this when you need a customer's balance or prepaid credits rather than, say, lago_get_customer or lago_get_customer_current_usage. The customer-scoped wording implies context but nothing is stated.

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