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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds that it wraps Clients.addNote and that staff_id defaults to BLESTA_STAFF_ID. This is useful but modest context; no hidden side effects or permission requirements are 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?

The description is brief and front-loads the purpose in the first sentence, followed by the underlying API method and default value. It contains some redundancy with the schema but 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?

The description plus annotations adequately cover purpose, example usage, and a key default for a 5-parameter tool with no output schema. It does not describe return values or side effects beyond creation, which is a minor 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 every parameter already has a clear description, so the description adds little beyond restating the staff_id default. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description opens with the specific verb 'Record' and identifies the resource, 'a staff note on a client account', with an example use case. This clearly distinguishes it from sibling 'get_client_notes' and other client management tools.

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 example 'e.g. summary of a support interaction' provides clear context for when this tool should be used. However, it does not explicitly contrast it with alternatives or state when not to use it.

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

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

Annotations already indicate the operation is not read-only, not idempotent, and not destructive. The description adds useful context about the same-currency requirement and that it consumes an unapplied balance, but it does not disclose side effects on the transaction's remaining balance, failure modes, or whether partial applications are allowed.

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 concise sentences with no filler. The primary action and constraint are front-loaded, and the 'Wraps Transactions.apply' note adds implementation context without 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 simple two-parameter operation, the description is mostly adequate, especially with annotations covering the safety profile. However, the absence of an output schema and any mention of return values, error conditions, or behavior when the unapplied balance is insufficient leaves gaps for an agent planning to invoke the 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 0% and the description does not explain transaction_id or amounts. It only implies their roles ('existing transaction' and 'one or more invoices'), leaving the agent to infer that amounts is an array of invoice_id/amount pairs from the schema structure. This is insufficient compensation for the lack of schema descriptions.

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

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

The description clearly identifies the action ('Apply'), the resource (an existing transaction's unapplied balance/client credit), and the target (one or more invoices). The 'same currency' constraint and the concept of existing client credit distinguish it from sibling tools like process_payment or record_manual_payment without requiring schema inspection.

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: this tool is for allocating an existing transaction's unapplied balance to invoices. However, there is no explicit guidance on when to choose this over related tools like record_manual_payment or process_payment, nor any exclusion criteria such as 'use only when the transaction is a credit'.

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 signal destructive and non-idempotent behavior, but the description adds substantial behavioral context: arbitrary public methods, named-parameter binding to PHP arguments, HTTP method inference, plugin model naming, timezone requirements, a documented error-handling retry, and the warning that 'Any valid API key has full administrative power'. These traits are not visible in the annotations and materially affect invocation.

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 dense but every sentence earns its place: invocation pattern, parameter semantics, plugin naming, HTTP inference, timestamp rule, error retry, and security warning. It is front-loaded with the core usage and then layers necessary caveats, which is appropriate for an open-ended escape-hatch tool.

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

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

Given the tool's deliberately open-ended nature and the absence of an output schema, the description is unusually complete: it covers how to construct model/method calls, pass parameters, handle nested data, choose HTTP verbs, format timestamps, recover from a specific server error, and understand privilege implications. An agent has enough to invoke it correctly across a wide range of Blesta methods.

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?

Although schema coverage is 100%, the description meaningfully expands parameter semantics: it explains that parameters are passed BY NAME and must match PHP method argument names, gives a nested-array example, specifies plugin.model naming, and defines how http_method is inferred when omitted. This goes well beyond the schema's property descriptions.

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

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

The description opens with 'Escape hatch: call any public model method of the Blesta API as {model}/{method}', naming a specific verb, resource, and invocation pattern. It also explicitly distances itself from the purpose-built sibling tools by warning to 'prefer the purpose-built tools when one exists', so an agent can tell it apart.

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 states when to use the tool ('escape hatch'), when not to ('prefer the purpose-built tools when one exists'), and gives concrete operational guidance such as inferring HTTP method from method name, using plugin.model syntax, and resending with all optional arguments on a specific error. This is explicit selection and usage guidance beyond any schema.

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

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

Annotations already mark it destructive; description adds concrete behavioral details: immediate vs scheduled execution, module deprovision when use_module is true with 'now', cron execution for scheduled cancellations, and the undo path via blesta_call services/unCancel. No contradictions with 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?

Three sentences, front-loaded with the core action, then the `when` breakdown, then the undo note. No filler; every sentence carries operational 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?

Given the 5-parameter schema and destructive annotation, the description covers timing, deprovisioning, and reversibility. It doesn't describe the return value (no output schema), but that's not required. Slightly more explicit guidance on when to prefer suspend_service would round it out, but the description is sufficient.

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 covers 4 of 5 parameters; description goes beyond by explaining the meaning of `when` options (default safest, immediate module deprovision) and ties `use_module` to the 'now' behavior. It doesn't add to service_id, but that's clear from context.

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 'Cancel' with resource 'service' and enumerates three timing options. Distinct from sibling suspend_service/unsuspend_service by the permanent cancel semantics. The 'Wraps Services.cancel' line anchors it to a known API.

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

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

Provides clear context on what the tool does and the safest default for `when`, but doesn't explicitly contrast with suspend_service or specify when to choose this over alternatives. The exclusion of temporary suspension is implied by the name and sibling list, 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?

Goes well beyond the annotations by disclosing default dates (now and now+7 days), the email queueing side effect via Blesta's cron, the draft/unissued behavior, and the return value (numeric invoice ID and stored invoice). This is substantial behavioral context for a non-read-only 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?

Three sentences, with the core action front-loaded and every sentence contributing either a default, a side effect, or the return value. No filler or redundancy.

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

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

Despite having 9 parameters and no output schema, the description covers the essential creation context, defaults, side-effect toggles, and return payload. The input schema handles field-level formats, so nothing critical is missing for an agent to invoke 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics for key parameters: deliver_by_email queues cron-based email, draft creates an unissued invoice, and date fields have explicit defaults. This exceeds what the schema alone 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 action ('Create a new invoice for a client with one or more line items') and names the underlying operation ('Wraps Invoices.add'). It is clearly distinguishable from sibling tools like update_invoice, send_invoice, and get_invoice.

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 primary use case unambiguous and clarifies mode choices (draft vs issued, deliver_by_email vs not). It does not explicitly name alternatives or say 'use update_invoice for existing invoices,' but the creation context is clear enough that an agent can infer when to call it.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds valuable behavioral details beyond that: the link does not expire, is tied to a specific client and invoice, refuses when ownership mismatches, and can fail on IonCube-encoded installs without BLESTA_SYSTEM_KEY. It also explains the internal token construction, making side effects and dependencies explicit.

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 first sentence is front-loaded with the core purpose, and every subsequent sentence conveys behavior or constraints relevant to correct invocation. It is longer than average, but the implementation detail, expiration warning, ownership restriction, and IonCube caveat all 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?

With no output schema, the description fully explains what the caller gets: a customer-facing URL with the exact format. It also covers failure conditions, ownership validation, expiration semantics, and environment-specific setup, so an agent has enough context to call this tool 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?

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description reinforces the ownership relationship between client_id and invoice_id by stating the call refuses mismatches, but it does not add meaningful syntax or format details beyond the schema.

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

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

The description states a specific action ('Produce a customer-facing URL') and the exact resource (invoice payment link without login), distinguishing it from sibling tools like verify_invoice_payment_link, which validates rather than generates. It also gives the concrete URL format, leaving no ambiguity about what the tool does.

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

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

The description makes the usage context clear: generate a non-expiring, customer-specific payment URL for the invoice's own customer. It includes an important exclusion ('Only hand it to the invoice's own customer') and explains that the call refuses mismatched ownership. It does not explicitly name alternatives, but the purpose is distinct enough to infer when it applies.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds valuable behavioral context by enumerating the exact fields returned and noting that settings are optional, which helps the agent anticipate the response shape. It does not describe error handling (e.g., what happens if ID not found) or rate limits, but these are minor gaps given the annotation coverage.

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

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

The description is a single, information-dense sentence that leads with the primary action and then lists the returned fields compactly. There is no fluff, but the field list is somewhat long and could be trimmed without loss. It is front-loaded with the verb and resource.

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 tool with two parameters and no output schema, the description is largely sufficient. It specifies the input (client_id) and the output scope (fields, including optional settings). It does not mention the return format (e.g., a single object) or behavior when the client is not found, which could be helpful. However, given the tool's simplicity and the read-only annotations, these omissions are acceptable.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description rephrases the 'include_settings' parameter as 'optionally, effective settings (currency, language, autodebit, ...)', which is nearly identical to the schema text and adds minimal new meaning. It adds no detail about the client_id parameter beyond what the schema states (numeric client ID, the `id` field).

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 ('Retrieve') and a precise resource ('one customer by numeric client ID'), and lists the fields returned (identity, contact details, status, client group, optional settings). This clearly distinguishes it from sibling tools like search_clients (which searches rather than retrieves by ID) and get_client_contacts (which focuses on a sub-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 clearly implies when to use it: when you have a numeric client ID and need the full client record, optionally with effective settings. However, it does not explicitly name alternatives or state when not to use it (e.g., use search_clients when you don't have an ID). The sibling list includes many related tools, but the description provides no explicit routing guidance.

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

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

Annotations already establish the read-only, idempotent, non-destructive nature. The description adds useful behavioral context beyond that by explaining that the balance is specifically the sum of open invoices and that status counts are included. It does not describe the exact response shape, but the annotations lower the burden for safety-related behavior.

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

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

The description is three concise sentences with no filler. It front-loads the primary result, then adds implementation detail and a routing hint, with every sentence contributing useful information.

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

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

For a simple read-only tool with two well-documented parameters and no output schema, the description conveys the core return value and important context about how the balance is calculated. The status list is abbreviated with '...', which leaves some ambiguity, but the overall guidance is sufficient for an agent to decide whether to call this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that the currency parameter is the currency in which the owed amount is expressed. It also points to get_client for discovering the client's default currency, which clarifies the intended use of the currency parameter.

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

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

The description clearly states the tool's function: it returns the amount a client owes in a given currency (sum of open invoices) plus invoice counts by status. It also distinguishes itself from related tools by explicitly referencing the underlying Invoices.amountDue and Invoices.getStatusCount operations.

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 concrete guidance for a related task: 'Use get_client with include_settings to learn the client's default currency.' This helps an agent decide between this tool and a sibling when currency information is missing, though it does not explicitly enumerate all alternative tools or exclusion conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds modest context by stating it wraps Contacts.getAll and Contacts.getNumbers and lists output fields, but it does not disclose pagination, error, or rate behavior.

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

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

Two short sentences, front-loaded with the output contract. The first sentence is dense and useful; the second sentence about wrapped methods is mildly informative but not essential, so it is not quite perfect.

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 with full schema coverage, the description plus annotations provide the core selection and invocation information: resource, returned fields, and safety. It does not specify response shape or pagination, but the low complexity and rich schema/annotations make it sufficient.

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 client_id, contact_type, and include_numbers. The description echoes the contact types and phone/fax numbers but adds no new parameter meaning beyond what the schema 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?

The description clearly identifies the resource ('contacts under a client') and enumerates returned fields and contact types, so an agent can tell it apart from client-level tools like get_client. It lacks an explicit verb and a named sibling comparison, which keeps it just below the top score.

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

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

There is no guidance on when to use this tool versus alternatives such as get_client or search_clients. The description implies 'when you need contacts under a client' but never states when/when-not or suggests a sibling tool.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds value by disclosing newest-first ordering, the inclusion of sticky notes, and the underlying wrapped methods, which goes beyond the structured annotations.

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

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

The description is two short sentences with no filler. The key behavioral facts are front-loaded, and the wrapper details add useful context without bloat.

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 two well-documented parameters, the description covers ordering, sticky notes, and the recommended usage context. There is no output schema, so it could have stated the return shape more explicitly, but the description is still sufficient 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 coverage is 100%, so both parameters are fully documented in the schema. The description adds only the generic 'client account' context and does not provide additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The title and description clearly identify the resource as staff notes on a client account, with a specific ordering (newest first) and inclusion of pinned/sticky notes. This is easily distinguished from sibling tools like add_client_note and get_client.

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 explicitly advises reading these notes before acting on an account, giving a clear usage context. It does not name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Beyond the readOnly/idempotent annotations, it discloses pagination, the 'active' default status, the extra API call per service when include_renewal_price is set, compact-by-default results, and the full raw-object mode. No hidden write behavior; no contradiction.

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

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

Four dense sentences, each carrying distinct information: purpose, wrapper behavior/defaults, single-service mode, and output mode. Front-loaded with the main purpose; no filler.

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

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

For a 7-parameter read-only tool with no output schema, it explains the returned shape (compact vs full), key fields, paging default, statuses, and the renewal-price cost. Nothing essential for selecting or invoking it correctly appears 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 coverage is 100%, so the schema already documents every parameter. The description adds meaningful semantics for service_id vs client_id, the per-service cost of include_renewal_price, and what full changes in output shape, going beyond the bare schema.

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

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

The description names a specific verb and resource ('List a customer's services') and details the returned attributes (status, package/pricing, renewal date and price), which clearly differentiates it from sibling tools like search_services. The single-service variant is also stated 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?

It gives clear usage context: pass client_id for a customer's service list or service_id to fetch one service, and notes the default status filter. It does not explicitly name alternative siblings or exclusion conditions, so it stops short of a 5.

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

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

Annotations already declare a safe read-only, idempotent operation, so the description's burden is lower. It adds useful behavior by noting it wraps getList/getListCount and by listing filters, but it does not clarify pagination behavior, status defaults, or how open-world results are bounded.

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

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

The description is a tight, front-loaded listing of returned fields, the underlying wrapper, and filters. Every clause adds information and there is no redundancy with title or schema.

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

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

For a read-only list tool with no required parameters, the combination of returned fields, wrapper method, and filter list is enough to call it correctly. Lacks explicit pagination/output format detail, but annotations and self-explanatory params keep the gap minor.

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

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

With only 40% schema coverage, the description partly compensates by naming the filter parameters, including the applied_status enum values. However, it stops at names and does not explain semantics for page, status, or amount/date ranges beyond what sparse schema comments say.

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?

Description clearly identifies the resource ('payment history for a client or all clients') and the operation (wrapping Transactions.getList/getListCount), and enumerates the data returned (amount, currency, type, status, gateway, reference, invoice application). This differentiates it from singular get_transaction and other client history tools.

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

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

The description implies when to use it by defining scope ('for a client (or all clients)') and enumerating filters, but it never explicitly states when to prefer this tool over siblings such as get_transaction or get_invoice_payments. Selection guidance is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying exactly what is read and that it wraps Invoices.get, without contradicting the annotations.

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

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

The description is efficient and front-loaded with the core action, followed by a useful field enumeration and usage note. The field list is somewhat long but earns its place since there is no output schema.

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

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

For a single-parameter read tool with no output schema, the description fully covers what it returns, how to identify the required input, and when to prefer a sibling tool. Nothing essential 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 coverage is 100% and the schema already explains that invoice_id is the numeric `id` field, not the displayed number. The description reinforces this distinction and ties it to the return field list, adding practical context beyond the schema.

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

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

The description states a specific verb and resource: 'Read one invoice by numeric invoice ID' and enumerates the exact fields returned. It clearly distinguishes this tool from search_invoices by noting the lookup key is the numeric ID, not the displayed number.

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 explicitly tells the agent when to use search_invoices instead: 'Use search_invoices first if you only know the displayed invoice number.' This gives clear routing guidance between two related tools.

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

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

Annotations already mark this as read-only and idempotent, so the description adds useful context by revealing the underlying Transactions.getApplied wrapper and the optional extra call per transaction via include_transaction_details. This explains behavior beyond what annotations provide.

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

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

Three tight sentences with no filler. The core action and output fields are front-loaded, and the optional-detail behavior is explained concisely.

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 appropriately lists the returned fields and the invoice summary. It is complete enough for a read-only tool, though it could mention behavior for invoices with no payments.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the meaning of include_transaction_details and mentions the returned transaction fields, but it does not materially add new parameter 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?

The description states a specific verb ('List') and resource ('payments applied to an invoice'), and enumerates the exact fields returned. It clearly separates this from sibling tools like get_client_transactions or get_transaction by anchoring to invoice-scoped payments.

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 intended use is clear: call this when you need the payments applied to a specific invoice and its paid/due summary. It does not explicitly name alternatives or exclusions, but the scoping is strong enough that an agent can select it correctly.

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, idempotentHint, and non-destructive behavior, so the description only needs to add context. It adds the composition of the response and references the underlying Packages.get method, but does not disclose edge cases, error behavior, or other traits beyond what annotations provide.

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

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

The description is compact and front-loaded: it states the scope first, then lists the included content, and ends with a short implementation note. Every clause adds value, and there is no redundant filler.

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

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

For a one-parameter read-only getter with comprehensive annotations, the description is mostly complete. It lists the return contents even though there is no output schema, which helps an agent understand what to expect. It does not discuss alternatives or error/not-found behavior, but these are not essential for the basic 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 0%, and the description does not explain package_id or its role beyond the implied 'one package'. The meaning rests entirely on the property name and type constraints in the schema, which is insufficient for a low-coverage tool that should compensate.

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

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

The description clearly identifies a single-package retrieval and enumerates what is included (pricing, description, module, configurable option groups, groups). It distinguishes from list_packages by emphasizing 'one package', though it does not explicitly name the sibling or state the action verb directly.

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 context is implied: 'One package in full' suggests this is for fetching full details of a single package, and list_packages is the obvious alternative for multiple packages. However, there is no explicit when-to-use guidance, exclusion criteria, or mention of when to prefer get_package over similar get_* tools.

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

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

Annotations already establish the read-only, idempotent, non-destructive nature of the operation. The description adds meaningful behavioral detail: results are masked and never include full numbers, and the tool wraps two specific account-retrieval methods. This goes beyond what annotations alone provide.

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

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

Three short sentences each earn their place: the first defines the output shape, the second states the masking guarantee, and the third gives implementation and usage context. There is 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 one-parameter read-only lookup, the description fully equips an agent: it states what is returned, the masked fields, the underlying wrappers, and when the tool is useful. The lack of an output schema is mitigated because the description enumerates the returned fields.

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

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

The schema has only client_id with no description, and the description refers to it only indirectly as 'a client has on file.' Because there is one self-explanatory required parameter, the gap is small, but the description does not explicitly define the parameter or its expected meaning.

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

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

The description clearly identifies what is returned ('Cards and bank accounts a client has on file'), enumerates the masked fields, and distinguishes this tool from siblings focused on invoices, transactions, or services. It also names the underlying wrapped methods, leaving no ambiguity about the resource and operation.

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

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

The description provides concrete use cases ('useful for autodebit failures and expired cards') that tell an agent when this tool is appropriate. It does not explicitly state when not to use it or name alternatives, but the intended context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds beyond annotations by revealing the tool aggregates three underlying calls (Quotations.get, getLineItems, getInvoices) and conditionally includes invoices only 'if any' were generated. This gives useful context about the tool's data scope and behavior.

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

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

The description is two sentences with no filler. The first sentence front-loads the core functionality (what is returned), and the second adds valuable implementation context. Both sentences earn their place, making this an appropriately concise and well-structured definition.

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

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

For a simple one-parameter read tool with comprehensive annotations and no output schema, the description covers the essential information: it returns a quote, its line items, and any related invoices. It lacks details on error behavior or response structure, but these are less critical given the tool's simplicity and annotation coverage.

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 0%, so the description must compensate for the single parameter, quotation_id. The description never mentions the parameter or explains how to use it (e.g., the ID of the quotation to fetch). While the name is self-explanatory, the description adds no additional meaning over the schema, which is a clear gap given the low 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: 'One quote with its line items and any invoices generated from it.' This clearly distinguishes it from sibling tools like list_quotations (plural) and get_invoice (invoice-specific), and the explicit mention of included line items and invoices makes the tool's scope immediately understandable.

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

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

The phrase 'One quote' strongly implies this tool is for fetching a single quotation by ID, contrasting with list_quotations. The description offers clear context for when to use it, though it does not explicitly name alternatives or state conditions to avoid using it. This is a minor omission, so 4 is appropriate.

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 convey read-only, idempotent, and non-destructive behavior. The description adds value by revealing that it wraps Services.get + Services.getActions(current_status) and that results depend on the service's current state, going beyond the annotations.

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

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

Two sentences deliver the core meaning, examples, and implementation context without filler. The key output and state-dependence are front-loaded.

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

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

For a simple one-parameter read-only tool, the description explains the output and the state-dependent nature of the result. It does not explicitly describe the return format or empty/error cases, but the examples and annotation coverage make it adequately complete for calling the tool.

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

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

The schema has 0% description coverage, so the description must compensate. It refers to 'a service' but does not explicitly name service_id or explain its role; the schema provides the integer constraint. The semantic connection is clear but implicit.

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

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

The description clearly states the tool's output: the operations Blesta allows on a service given its current state, with concrete examples. This distinguishes it from action siblings like suspend_service or cancel_service and from service-listing tools like get_client_services.

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 use case is clear: determine which operations are valid for a service in its current state before performing an action. It does not explicitly name alternatives or exclusions, but its unique purpose makes the intended usage evident.

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, idempotentHint, and non-destructive behavior. The description adds useful context beyond those: it is a composite of Transactions.get and Transactions.getApplied(transaction_id), which explains that the result combines two underlying calls.

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

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

Two short sentences with no filler. The return behavior is front-loaded, and the implementation note is compact and relevant.

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 getter, the description sufficiently explains what is returned: one payment plus its applied invoices. It does not detail response shape or error behavior, but the simple schema and strong annotations reduce the need for more.

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 0%, so the description must carry meaning for transaction_id. It only mentions the parameter by name in the wrapper note and ties 'transaction' to 'payment' in the first sentence. This is thin but adequate for a single, self-explanatory integer ID.

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

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

The description opens with a concrete result: 'One payment in full plus the invoices it was applied to.' It also names the underlying calls it wraps, which makes the resource and scope explicit. This clearly distinguishes it from list-style siblings like get_client_transactions and get_invoice_payments.

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

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

The description implies the use case: retrieve one payment and the invoices it was applied to. However, it never explicitly states when to prefer this tool over siblings or when not to use it, leaving routing to the agent's inference.

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

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

It discloses important behavioral traits: packages are not returned with prices by default, enabling include_pricing triggers one Packages.get call per package, and there is a 25-package limit. These details add value beyond the annotations, which already declare read-only, idempotent, and non-destructive behavior.

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

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

The description is concise and well-structured, front-loading the core purpose, then adding essential behavioral notes. Every sentence serves a purpose, and there is no redundancy or fluff.

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

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

The description is fairly complete for a listing tool: it covers pricing behavior, full mode, and the underlying API methods. It does not detail every parameter or the exact return format, but those are either in the schema or acceptable for a list operation.

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

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

The description adds meaning to include_pricing (how it works, the 25-call limit) and full (raw objects incl. descriptions), which are not fully explained in the schema. However, it does not elaborate on other parameters like include_hidden or package_group_id, and schema coverage is 63%, so it only partially compensates.

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

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

The description clearly states the tool lists packages and package groups, specifying it wraps Packages.getAll and Packages.getAllGroups. It also distinguishes from a single-package retrieval tool like get_package by its list nature, making the purpose 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 explicit guidance on when to set include_pricing and warns about the 25-package limit, implying filtering before enabling pricing. It does not explicitly contrast with alternatives like get_package, but the context makes the intended use clear.

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, idempotentHint, openWorldHint, and destructiveHint false, so the safety profile is covered. The description adds that it wraps Quotations.getList / getListCount and enumerates statuses, but it does not disclose pagination behavior, default status, or return 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?

The description is three short sentences with no filler. It front-loads the purpose, then gives the implementation wrapper and the valid statuses, making it easy to scan.

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, safe list operation with three optional parameters and no output schema, the description conveys the essential calling pattern. The main omissions are pagination/return details, but page is self-describing and optional, and annotations already carry the read-only safety context.

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 0%, so the description must compensate. It adds meaning for client_id ('for a client or across all clients') and status ('by status' plus the status list), but the page parameter is left to its name and schema default. The status enumeration repeats 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?

The description identifies the resource as quotations/estimates and communicates the two main axes: client scope ('for a client or across all clients') and status filtering. It does not explicitly name the sibling get_quotation, but the plural list framing and optional client scope make the distinction reasonably clear.

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

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

The description implies when to use the tool: when listing quotations for one client or all clients, filtered by status. It does not state when to prefer get_quotation or another sibling, nor does it give explicit exclusions or alternative 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?

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context by naming the underlying wrapped calls and by disclosing that providing `package_ids` causes an additional lookup. This conditional behavior is not visible from the schema or annotations alone.

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 carry all essential information: the validation scope is front-loaded, and the conditional `package_ids` behavior is stated in one clause. There is no repetition of schema details or filler.

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

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

For a simple read-only lookup with two parameters and no output schema, the description covers the input semantics, the validation scope, and the conditional behavior. It does not explicitly describe the return shape or nonexistent-code behavior, but the listed validation fields effectively signal what the agent can expect to learn from the result.

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 50%: `package_ids` has a schema description, but `code` does not. The description compensates by identifying `code` as the promo code to validate and clarifying that `package_ids` are packages checked for coupon eligibility. This adds real meaning beyond the raw schema fields.

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

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

The description opens with a specific verb ('Validate') and resource ('a promo code'), then enumerates exactly what is checked: existence, status, dates, usage limits, per-currency discounts, and eligible packages. This is far more specific than the title and makes the tool's role 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 clearly frames when to use this tool: to validate a promo code and check its applicability. It also provides conditional guidance for the `package_ids` parameter by noting that it triggers an additional `Coupons.getForPackages` check. There is no explicit when-not-to-use statement, but no coupon-specific sibling tool exists, so the guidance is adequate.

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 flag destructive/non-idempotent behavior, and the description adds valuable context: 'Moves real money', receipt sending unless disabled, and the disabled-by-default environment gate. It does not detail failure modes or partial invoice application, but it meaningfully extends the annotation profile without contradicting it.

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

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

Five short sentences, front-loaded with the core action and outcome. Every sentence earns its place, and the critical warnings ('Moves real money', disabled state) are placed efficiently without filler.

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

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

For a destructive financial mutation with 8 parameters, a nested object, and no output schema, the description covers side effects and the enablement gate but omits the return value/error contract and exact invoice-application semantics. An agent would still need to infer what a successful call returns.

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 only 38%, so the description must compensate. It helps with account_id ('from get_payment_accounts'), type (stored card vs bank account), invoices (mapping and total constraint), and email_receipt ('unless disabled'). However, amount, currency, and staff_id remain unexplained, leaving a notable gap.

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

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

The description uses a specific verb ('Charge') and names the resource ('client's stored card or bank account through the payment gateway'), plus the outcome ('apply the result to invoices'). It clearly differentiates this from manual-payment or invoice-link siblings by emphasizing stored-account-only charging.

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 provides clear context: use this when charging a stored account and applying payment to invoices, and it gives an exclusion ('raw card data is never accepted') plus an activation requirement ('set BLESTA_ALLOW_PAYMENTS=1'). However, it never explicitly names sibling alternatives such as record_manual_payment or create_invoice_payment_link.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds valuable context beyond that: it wraps Transactions.add then Transactions.apply, explicitly states no charge is performed, and explains the optional application behavior. This gives the agent a clear mental model of side effects without contradicting any 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?

Three sentences with no filler. The main purpose is front-loaded, followed by the key distinction (does not charge) and a critical parameter behavior. Every clause earns its place and the description is easy to parse quickly.

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 moderately complex 7-parameter tool with no output schema and annotations present, the description covers the essential behavior, the internal wrapper, and the optional application logic. It doesn't mention prerequisites (e.g., client must exist, currency validity) or what the response contains, but those are less critical for correct invocation and are partly implied by schema constraints.

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 only 57%, so the description needs to compensate for undocumented parameters. It adds meaningful semantics for apply_to (omission yields unapplied credit) and clarifies the overall purpose of amount and client_id through context. However, it doesn't explicitly detail client_id, amount, or currency beyond what the schema's types imply, leaving some ambiguity for those required fields.

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

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

The description uses a specific verb ('record') and resource ('offline payment'), names concrete examples (bank transfer, cash, check), and explicitly states what it does not do ('Does not charge anything'). It distinguishes itself from charging/payment tools like process_payment by emphasizing it only records already received money.

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 frames when to use this tool: for offline payments already received, not for charging. It also provides conditional guidance on apply_to ('Omit apply_to to leave the amount as unapplied credit'). It doesn't explicitly name sibling alternatives or when-not conditions, but the 'does not charge' clause implicitly differentiates it from charging tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is covered. Description adds that it wraps Clients.search, returns a page of client records including primary contact and status, and points to get_client for more details. This gives useful context about return shape and suggests a follow-up action. Slight gap: does not explicitly state pagination behavior, but 'page' parameter implies it.

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

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

3 sentences with no fluff. Front-loads what it does and what it returns, then gives a pointer to get_client. Could be slightly clearer on pagination, but overall efficient. Slightly long but justified by the need to explain query fields and return contents.

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?

Fully competent for a read-only search tool. The schema has all parameter details, annotations cover safety, and description explains return contents and follow-up. The only missing element is explicit statement about pagination limits, but the page parameter and default are self-explanatory given schema coverage.

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 covers both parameters fully with descriptions. Description adds value by clarifying the query can include client ID code and lists exact fields to search, which goes beyond schema's 'Text to search for'. This helps the agent form effective queries.

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?

Description clearly states it searches for customers with free-text query across specific fields (email, name, company, ID code). Includes example of ID code format. Distinguishes from siblings by focusing on search vs. specific get operations.

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

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

Clearly states use cases (searching customers) and suggests using get_client for full details. Does not explicitly say when NOT to use this, but the guidance for alternatives is clear. No mention of when to use other search tools like search_invoices or search_services, but those are targeted at different resources.

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 this read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful behavior: it wraps two underlying methods, applies a default status of 'open', and discloses what fields each result contains. This goes beyond the annotations without contradicting them.

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 sentences, numbered modes, and no filler. The critical constraint ('Provide at least one of `query` or `client_id`') and result contents are both front-loaded and expressed 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?

With no output schema, the description compensates by enumerating the result fields (`id`, `id_code`, status, dates, total, paid, due). It covers the two usage modes, required-parameter constraint, and default status. The remaining parameter details are fully documented in the schema, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by mapping `query` and `client_id` to underlying methods, clarifying that status defaults to 'open', and explaining the free-text search scope. It does not repeat every schema detail but enhances the semantics of the key parameters.

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

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

The description opens with a specific verb and resource ('Find invoices') and immediately lays out two distinct search modes. It names exact searchable fields (invoice number, client name/email, line description) and the alternate client_id listing path, making the tool's role clear relative to single-invoice retrieval tools like get_invoice.

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 explicit selection guidance: use `query` for free-text search or `client_id` for status-filtered listing, and states 'Provide at least one of `query` or `client_id`.' It does not explicitly mention sibling alternatives or when not to use this tool, but the in-tool mode guidance is strong.

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 the operation safe, read-only, idempotent, and non-destructive. The description adds useful context by revealing that it wraps Services.search, explains search_fields behavior, and states the return format ('compact service records with client_id'), which is valuable given there is no output schema.

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

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

Three focused sentences with the primary purpose front-loaded, followed by the wrapper context and return shape. No filler or redundant restatement of schema details.

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 search tool, the description covers purpose, scope, searchable fields, wrapper behavior, and return format. It does not detail pagination behavior or the exact contents of compact records, but the annotations and schema provide sufficient safety and defaults 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 coverage is 75%, and the description enriches the query and search_fields parameters with concrete examples such as domain, hostname, username, package name, and service number. The full and page parameters remain only schema-documented, but the description adds meaning beyond the schema overall.

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?

Description states a specific verb and resource: 'Find services across all clients by domain, hostname, username, package name or service number.' The phrase 'across all clients' differentiates it from sibling tools like get_client_services, and the service focus distinguishes it from search_clients.

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 broad cross-client search but does not explicitly state when to prefer this over get_client_services or other alternatives. There are no direct exclusionary guidelines or named sibling alternatives, so usage context is only implied.

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

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

The description discloses key behavioral traits beyond what annotations provide: the actual send is performed by Blesta's cron within minutes (asynchronous), and the tool returns a delivery log to view prior sends. These details about timing and return value are not covered by the annotations (readOnlyHint=false, openWorldHint=true, etc.). It adds meaningful context that helps the agent predict the tool's non-immediate effect and output, earning a 4.

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 zero filler. The first sentence front-loads the primary action (queue delivery) and the method, while the second adds the cron timing and log behavior. Every sentence earns its place, making it highly concise and well-structured.

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 tool with only two parameters, no output schema, and no nested objects, the description is complete. It explains the action, the asynchronous nature (cron), and the return value (delivery log). An agent has all the information needed to call the tool correctly without missing critical details.

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?

Both parameters (invoice_id and method) are fully described in the schema (100% coverage), so the baseline is 3. The description does not add significant new meaning to the parameters; it mentions 'email or another configured method' which aligns with the method param but adds no new syntax or constraints. It also notes the return of a delivery log, but that's not parameter-related. Thus, it meets the baseline without exceeding it.

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

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

The description clearly states the tool queues delivery of an invoice to a client via email or other methods, naming the wrapped API (Invoices.addDelivery). It specifies the exact resource (invoice) and action (queue/re-deliver), making the purpose unambiguous. While no sibling tool performs the same function, the verb+resource combination is precise and distinct.

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 usage by stating it sends invoices, but it does not explicitly guide when to use this tool versus alternatives or mention exclusions. There is no mention of when not to use it or what scenarios would favor another tool, though the absence of a sibling 'send' tool makes the implicit guidance sufficient. Still, explicit alternative guidance is missing, so the score is a 3.

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 destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating, potentially destructive operation. The description adds that suspension may also affect the server/module via `use_module`, which is valuable context. However, it does not explain side effects like what happens to the service, whether it's reversible, or any permissions required.

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

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

The description is a single sentence plus a parenthetical, which is concise and front-loads the core action. It doesn't waste words, though it could arguably be even more compact. The structure is adequate.

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

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

Given the tool's moderate complexity (4 params, one required) and that it's a destructive action, the description plus annotations cover the basics. However, there is no output schema and no mention of what the return value indicates (e.g., success/failure), which could be important for the agent to confirm the operation succeeded. Also, no guidance on edge cases like suspending an already suspended service.

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 75%, and the schema provides good descriptions for reason, staff_id, and use_module. The description adds the crucial conditional behavior tied to `use_module`, which is not fully explicit in the schema. However, service_id has no description in the schema, and the description does not clarify it either, leaving a minor gap.

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

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

The description clearly states the verb 'Suspend' and the resource 'service', and it distinguishes the additional behavior when `use_module` is true. It also names the underlying method it wraps, which adds specificity. However, it doesn't explicitly differentiate from its sibling 'unsuspend_service', though the opposite action is obvious from the name.

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

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

The description implies when to use this tool: when you need to suspend a service, and includes the nuance about the module suspension. However, there is no explicit guidance on when NOT to use it, nor does it mention prerequisites such as whether the service must exist or be active. It does not mention that 'unsuspend_service' is the alternative for reversing the action.

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 indicate this is a non-read-only, non-destructive action. The description adds the behavioral detail that the module is also reactivated when `use_module` is true, but does not disclose edge cases like error conditions or behavior when the service is already active.

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

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

One concise sentence with a clear front-loaded action. The `use_module` clarification earns its place, while 'Wraps Services.unsuspend' is slightly redundant but not harmful.

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

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

For a tool with one required parameter and annotations covering safety, the description covers the core purpose but lacks guidance on when to use it versus siblings and does not address potential failure modes or return expectations.

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 only 33% (staff_id), leaving service_id and use_module undocumented. The description clarifies `use_module` by explaining its effect, but does not add meaning for service_id or staff_id beyond the schema.

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

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

The description states a specific action ('Reactivate') and resource ('a suspended service'), and the note about `use_module` clarifies scope. This clearly distinguishes it from the sibling inverse tool `suspend_service`.

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

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

Usage is implied by the verb and name, but there is no explicit guidance on when to choose this over `suspend_service` or other service-related tools. No prerequisites or exclusions are described.

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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds key behavioral detail: inactive/fraud clients cannot log in)Skip and fraud additionally blocks orders. It also reveals the underlying API call (Clients.edit), giving the agent a useful mental model of the mutation.

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 dense sentences with no filler. The main action is front-loaded, the enum values are named, the wrapper target is stated, and only meaningful behavioral consequences are included. Every clause earns its place.

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

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

Given the simple schema, strong annotations, and lack of an output schema, the description is sufficient for an agent to invoke the tool correctly. It covers the action, status options, effects of status changes, and the underlying endpoint without leaving critical 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 coverage is 100% and both parameters are documented in the schema. The description adds value by explaining the real-world meaning of each status enum value and clarifies how the parameters map to the underlying Clients.edit call.

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

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

The description clearly states the operation ('Set a client's status'), the resource (client), and the allowed values (active, inactive, fraud). The explicit 'Wraps Clients.edit(client_id, {status})' line also distinguishes this from read-only sibling tools like get_client and search_clients.

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 implies exactly when to use the tool: whenever a client's status needs to be changed. The description does not explicitly contrast with alternative tools, but no sibling tool covers status updates, and the behavioral consequences ('cannot log in', 'blocks orders') provide clear and practical usage 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 signal destructive behavior and non-idempotence, and the description adds important context by warning that voiding is 'irreversible in practice' and only appropriate for unpaid invoices. It also discloses that this wraps Invoices.edit, giving a bit of implementation grounding beyond the annotations.

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

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

The description is three tight sentences with the core edit capability first, followed by the irreversible void warning and the line-item exclusion. Every sentence adds actionable information with no filler.

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

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

For a mutation tool with no output schema, it covers the key fields, the dangerous void behavior, and the important limitation that line items cannot be edited here. It could go further by noting permission requirements or response behavior, but it is sufficient for correct invocation in most 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 coverage is only 50%, and the description partially compensates by naming status, due date, billed date, and notes. However, it does not explain the distinction between note_public and note_private, and it adds little beyond the schema's existing descriptions for the date fields.

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

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

The description uses a specific verb ('Edit') and resource ('invoice header fields') and enumerates the exact editable fields. It also distinguishes itself from line-item editing, so an agent can tell it apart from the related invoices/edit path.

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

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

It explicitly states that line items are not editable here and directs the agent to use blesta_call invoices/edit with `lines` instead. It also gives a concrete usage condition for the `void` status, clarifying when this tool should be invoked.

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 mark the call as read-only/idempotent, and the description adds meaningful behavioral detail: internal decryption via Encryption.systemDecrypt, wrapping of Invoices.verifyPayHash and Invoices.get, and a concrete IonCube install failure mode tied to BLESTA_SYSTEM_KEY. No contradiction with 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?

Three tight sentences: purpose, input alternatives, and a critical environment-dependent failure. Each sentence carries distinct information and the purpose is front-loaded.

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

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

For a read-only verification tool with no output schema, the description explains purpose, input variants, and an environment failure, and notes the outcome ('whether payment is still due'). It doesn't specify the exact return payload shape, but that is a minor gap given the simple check semantics.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds operational meaning beyond the schema by explaining the hash-versus-sid alternatives, the required pairing of hash with client_id, and the decryption treatment of sid. This is more than the schema alone 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?

Description opens with a specific action ('Check that a payment link/hash is valid'), scopes it to 'a given client and invoice', and names the outcome ('report whether payment is still due'). This clearly separates it from siblings like create_invoice_payment_link.

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 states the two accepted invocation modes (raw hash + client_id, or sid/full URL) and clarifies how they are processed, but it gives no explicit when-not-to-use guidance or named alternatives. The intended context is clear from the purpose.

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