Bsale MCP by usefulapi

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

Annotations already establish this as a safe, read-only, open-world call, so the description's added burden is modest. It earns credit for spelling out the shape of the returned data (overdue, upcoming, total, per-document amounts) since there is no output schema, but says nothing about pagination, limits, or behavior when a client has no debt.

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

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

Two short sentences with the payload described first and the identifier requirement second; the endpoint path at the end is mildly redundant but cheap. 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 three-parameter read with no output schema, the description covers what matters: the data returned, the overdue/upcoming split, and how to identify the client. The remaining gap is the ambiguous case where no identifier is given, which the schema leaves open.

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 67%, and the description compensates by clarifying that client_id and client_code are alternatives for the same lookup, which the schema alone does not state since nothing is marked required. It does not, however, explain the default for as_of or what happens when neither identifier is supplied.

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 concrete resource and scope: a client's receivables, split into overdue vs upcoming debt, total owed, and the individual unpaid documents with amounts. That is specific enough to distinguish it from bsale_get_client or bsale_list_documents, although it never names a sibling 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?

'Give client_id or client_code' is a calling constraint, not usage guidance. Nothing says when this report is preferable to bsale_list_documents or bsale_get_client, and there are no exclusions or preconditions beyond the identifier requirement.

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 beyond the annotations by disclosing that the new client is visible instance-wide, that a duplicate tax id is rejected, and what the minimum required payload is. These are real operational constraints not available from readOnlyHint/idempotentHint/destructiveHint. It still doesn't mention what is returned (e.g., the new client id) or any auth/rate-limit expectations.

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 tight sentences, front-loaded with the WRITE marker and endpoint. Every sentence carries a constraint; nothing is 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 non-idempotent write with 13 mostly optional params and no output schema, the description supplies the key behavioral facts (visibility, dedup, minimum payload). Only the return value and the idempotency implication of retries are unaddressed.

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

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

Schema description coverage is only 38% across 13 parameters, so the description should compensate more. It adds the first_name-or-company requirement and ties 'code' to tax-id uniqueness, but leaves email format, phone, address, note, and is_foreigner behavior to the schema.

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

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

States a specific verb and resource ('create a new customer in Bsale') plus the underlying endpoint POST /v1/clients.json. An agent can immediately distinguish this from bsale_update_client, bsale_get_client, and bsale_list_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 'Give at least a first name or a company' rule tells the agent the minimum viable call, and the tax-id uniqueness note warns about failures. However, it never says when to prefer bsale_update_client over creating, or to check bsale_list_clients/bsale_get_client first for duplicates.

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?

Adds real context beyond the annotations: the call changes the document's receivable balance in the books and cannot be undone through this API — a critical irreversibility warning that destructiveHint=false alone would not convey. It stops short of describing validation failures or what the response contains, so it is not fully complete.

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 short sentences, all load-bearing: operation type first, then irreversibility, then prerequisites, then endpoint. 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 4-parameter mutation with no output schema, the description covers the operation, its side effect, its permanence, and its prerequisites. It omits what the API returns on success and any amount-validation behavior, which would be helpful but are not blocking.

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 25% schema description coverage, the description must compensate, and it partially does: it explains that amount should be verified against unpaid documents and where payment_type_id comes from. document_id is only implied by 'against an issued document', and constraints (amount > 0, paid_on defaulting to today) are left to the schema, so compensation is only partial.

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?

Opens with a specific verb and resource ('record a payment against an issued document') plus the typical scenario (normally a credit sale still unpaid), and the 'WRITE:' prefix distinguishes it immediately from the read/list siblings such as bsale_list_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?

Explicitly names two prerequisite calls and when to make them: check the amount with bsale_client_unpaid_documents and obtain payment_type_id from bsale_list_payment_types. This is exactly the routing information an agent needs before invoking.

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, but the description adds genuinely new context: stock levels and cost are mutated, and there is no undo available through this API. That irreversibility warning is the most important thing an agent needs to know for a write tool. It still omits permission requirements, duplicate-submission risk (relevant given idempotentHint=false), and error behavior.

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

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

Four short sentences, front-loaded with the WRITE marker and the additive behavior, then line structure, then the risk warning, then the endpoint. Every sentence carries distinct information with no repetition of the schema or title.

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

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

For a non-idempotent write tool with no output schema, the description covers what is mutated and that it cannot be reversed, which is most of what an agent needs. It falls short on what happens on failure or retry (important since the operation is not idempotent) and on how to identify offices, which siblings like bsale_list_offices would supply.

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 60% schema coverage, the description compensates by explaining the mutually-exclusive identification semantics for each detail line (variant by id, SKU code or barcode) — a constraint the schema does not encode with any oneOf. It still leaves note, document and document_number unexplained beyond their short schema blurbs.

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

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

States a specific verb and resource ('record a stock reception') plus the precise effect ('ADDS quantities to an office's inventory'), which is exactly what separates it from the read-only siblings like bsale_list_stocks. The parenthetical Spanish term and the WRITE prefix remove any ambiguity about operation type.

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?

'Confirm the numbers first' implies a precondition before invoking, which is useful usage context. However, no alternatives are named and there is no explicit statement of when-not to use this (e.g. for transferring between offices or correcting a prior reception), so the guidance remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the HTTP GET path and the expansion side-effect (extra data returned), but says nothing about auth requirements, rate limits, or what happens when the id does not exist.

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

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

Three short sentences, front-loaded with the identity of the resource, then the optional expansion, then the endpoint. Every sentence carries information, though the raw endpoint string is marginally redundant for an agent that already has the tool binding.

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

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

For a two-parameter read tool with annotations covering safety, this is close to adequate, but there is no output schema and the description never indicates what a client object contains or what expand actually changes in the response shape. Error behavior for a missing id is also absent.

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 0%, so the description must compensate — and it does for the harder parameter, enumerating valid expand values (contacts, attributes, addresses) that the schema does not list (only a generic pattern applies). client_id is only implied by "by id" and gets no detail on valid ranges or where to obtain one.

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

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

States a specific verb and resource ("One customer by id") plus the exact endpoint, so an agent knows this is a single-record fetch. The singular "One customer" implicitly contrasts with bsale_list_clients, but no sibling is named explicitly.

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

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

The description explains the optional expand mechanism (contacts, attributes, addresses), which is genuine usage guidance for the one non-obvious parameter. It gives no when-not guidance, no mention of when to prefer bsale_list_clients or bsale_update_client, and no note on invalid-id behavior.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that: the shape of the returned record and the fact that related records are excluded unless explicitly requested via expand, which materially changes the result set.

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

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

Two tight sentences plus the endpoint path, with the core purpose and the expand mechanism front-loaded. Every sentence earns its place; the raw path is mildly redundant but useful for API mapping.

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

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

With no output schema, the description does the work of sketching the return payload and the optional expansions, which is sufficient for an agent to call it correctly. Rate limits or error behavior are unmentioned, but that is a minor gap for a simple read.

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% — document_id is documented, but expand has only a type/pattern and no enum or explanation. The description compensates by enumerating the seven accepted expand values, which is the single most important piece of missing information.

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

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

States a specific verb and resource — fetch a single document by id — and enumerates the payload contents (amounts, dates, state, links). The singular "one document by id" implicitly separates it from bsale_list_documents, but no sibling is named 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 tells the agent to use expand for line items, payments and related records, which is actionable guidance for a common follow-up need. However, it never states when to prefer this over bsale_list_documents or which sibling to use when the id is unknown, leaving selection largely 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the endpoint and the effect of expand, but does not mention error behavior, authentication needs, or response format.

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

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

The description is short and front-loaded: it states the core retrieval, then the expand behavior, then the endpoint. Every clause adds useful 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 simple read operation, the description covers the basic purpose and one optional parameter. However, with no output schema and 0% schema description coverage, it leaves gaps around product fields returned and full expand parameter 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 0%, so the description must carry parameter meaning. It identifies the id-based lookup and explains that expand=[product_type] adds the product type, but it does not name product_id directly, document the array constraints, or list other valid expand values.

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 retrieval action for a product by id, which clearly distinguishes it from list-style siblings such as bsale_list_products. It could more explicitly contrast with bsale_get_variant or name the tool's role, but the resource and scope are 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 phrase 'by id' implies when to use this tool, and the expand note gives a usage hint. However, it does not explicitly state when to use it instead of bsale_list_products or bsale_get_variant, nor does it mention prerequisites.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the REST path and the expand behavior, but says nothing about error behavior for unknown ids or what the response body contains.

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

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

Three terse clauses, front-loaded with the resource and scope, then the expand hint, then the endpoint. Nothing is redundant.

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

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

For a simple two-parameter read with no output schema, the description covers identity and one optional behavior, but leaves the allowable expand vocabulary and the returned variant fields unexplained, which is the main thing an agent still needs.

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 0%, so the description must carry parameter meaning, and it only partially does: it gives expand=[product] as an example but the schema permits an array of up to 8 entries matching ^[a-z_]{1,40}$, and no other valid expand values are listed. variant_id's type and constraints (positive integer) are left entirely to the schema.

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

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

States a specific verb (get) and resource (one variant/SKU) scoped by id, which cleanly separates it from bsale_list_variants. It also names the endpoint, though it never explicitly references the sibling tool.

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

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

Usage is only implied: 'by id' signals single-record retrieval versus listing, and the expand hint suggests when to request embeddings. There is no explicit statement of when to use this versus bsale_list_variants or bsale_get_product.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds only the HTTP endpoint, and says nothing about pagination behavior, default active-only scoping, rate limits, or result caps (limit max 50).

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

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

Two tight sentences: field inventory first, filters second, endpoint last. No filler, and the most decision-relevant information is front-loaded.

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

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

With eight parameters, 50% schema coverage and no output schema, listing the returned fields is valuable compensation. But it omits pagination semantics (offset/next_offset), the limit cap, the state filter, and expand, all of which an agent needs to page or shape the response 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 50%, and the description compensates by naming four of the eight filters (code/tax id, name/first name, last name, email) and clarifying that code is the tax id. It says nothing about state, expand, limit, or offset, so it does not fully close the coverage 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?

States a specific verb+resource ("List customers") and enumerates the returned fields plus the backing endpoint, so the agent knows exactly what this returns. It does not explicitly contrast with bsale_get_client or bsale_client_unpaid_documents, leaving sibling differentiation to inference from the names.

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

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

"Filter by tax id, name, last name or email" implies the retrieval use case, but there is no explicit when-to-use guidance, no statement that this is for browsing/searching versus fetching one client via bsale_get_client, and no mention of when the filter combinations are 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 cover the safety profile (readOnly, non-destructive, openWorld), so the bar is lower; the description still adds value by disclosing the default newest-first ordering, the field set returned (amounts, state, SII status, public PDF link) and the underlying endpoint. It stops short of mentioning pagination behaviour or any rate/volume limits beyond what the schema states.

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

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

Three tight sentences: what is returned and in what order first, then filters, then expand, then the endpoint. Every clause carries distinct information and nothing is repeated from the 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 13-parameter tool with no output schema, the description does the heavy lifting on return shape, ordering and expand semantics. Remaining gaps (pagination via limit/offset/next_offset, the state=active/inactive switch) are already documented in the schema, so completeness is high but not exhaustive.

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 85%, so the baseline is 3, but the description earns extra credit by enumerating the filter dimensions and, importantly, naming the allowed expand values (details, payments, client, office, document_type) — the schema only constrains expand items with a generic pattern, so this is information an agent could not get otherwise.

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

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

States a specific verb and resource ('List issued documents') and immediately enumerates the concrete document kinds returned (boletas, facturas, notas de credito, guias), plus ordering, returned fields and filters. It also cross-references the sibling bsale_list_document_types for the document_type_id filter, so an agent can tell it apart from bsale_get_document (single record) without opening either schema.

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?

Gives clear usage context: which fields can be filtered on (emission date range, document type, client, office, folio, SII code) and that expand should be used to embed related data. It does not, however, state when to prefer this over alternatives such as bsale_get_document, bsale_client_unpaid_documents or bsale_sales_summary, nor any exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that results include an id and an SII tax code plus the underlying endpoint (GET /v1/document_types.json), but says nothing about pagination behavior or how the default active-only state filter affects results.

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

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

Two short sentences with zero filler: the resource and return fields come first, followed by the actionable usage note and endpoint. Nothing is repeated from the schema or annotations.

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 small reference-lookup tool with read-only annotations and no output schema, the description covers what the tool returns and why it matters. The remaining gap is paging/default-state behavior, which an agent would need when the catalog is large.

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%, so most parameters are already documented; the mention of the "tax (SII) code" gives indirect meaning to code_sii, which is the one undocumented parameter in the schema. The description does not explain limit/offset paging or the state filter, so it adds only marginal value beyond the schema.

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

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

States a specific verb and resource ("List document types") and immediately grounds it with concrete examples of the records returned (boleta, factura, nota de credito, guia de despacho). It also names what each record carries (id and SII tax code), which cleanly separates it from sibling bsale_list_documents, which lists actual documents rather than the type catalog.

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?

"Use the id when filtering documents" implies the intended workflow (resolve a type id, then filter with it), but there is no explicit when-to-use/when-not or a named alternative. An agent can infer the role but must connect the dots to bsale_list_documents itself.

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, and destructiveHint=false. The description adds the returned fields and endpoint, which is helpful, but does not add deeper behavioral context such as auth requirements or rate limits.

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

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

The description is short and front-loads what the tool does and why it matters. The trailing 'GET /v1/offices.json' is technical and slightly less useful for tool selection, but it does not distract significantly.

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

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

For a simple paginated list tool with full schema coverage and no output schema, the description covers purpose, returned fields, and a key downstream usage. Pagination and state filtering are left to the schema, which is acceptable here.

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

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

Schema description coverage is 100%, so limit, state, and offset are fully documented in the schema. The description does not add input-parameter semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'List branches (sucursales)' with the returned fields 'name, address and cost center'. It is unambiguous against siblings such as bsale_list_stocks or bsale_list_documents because the resource is offices/branches.

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?

'Use the id for stock and document filters' gives a clear downstream use case for the returned IDs, but it does not state when not to use this tool or name an alternative. The guidance is useful but incomplete.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds the concrete endpoint (GET /v1/payments.json) and the returned field set, but says nothing about pagination behavior beyond what the schema states or about result volume.

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

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

Two tight sentences: the first covers output shape, the second covers filtering, and the endpoint closes it out. No filler and the returned-field list 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?

With no output schema, the description usefully compensates by naming the fields returned, and it covers the main filter dimensions. Minor gap: it doesn't mention pagination or expand, though those are schema-documented, so an agent can still call it 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 71%, so most parameters are already documented, and the description reinforces the paid_on, document_id and code_sii+number pairing. It adds no syntax or format detail beyond the schema and omits limit/offset/expand entirely, so it is a baseline-level contribution.

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 ('List payments received') and enumerates the returned fields (amount, date, payment type, document, office, user), so the agent knows exactly what this returns. It does not explicitly differentiate itself from siblings like bsale_list_payment_types or bsale_list_documents, keeping it just short of a 5.

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

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

It states the available filters (payment date, document id, tax code plus folio), which implies how to narrow results, but there is no guidance on when to choose this over sibling listing tools or when filters are required. Usage is inferable but not spelled out.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete endpoint (GET /v1/payment_types.json) and what a record contains (an id), but says nothing about result volume, pagination behavior, or ordering — all of which are left to the schema.

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

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

Two compact sentences plus an endpoint reference, with the identifying purpose (getting ids for payment recording) front-loaded. 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 simple zero-required-parameter read tool with full schema coverage and supporting annotations, the description covers what it returns and why. The absence of an output schema is partly mitigated by naming the key field, though the response envelope itself remains unspecified.

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 each parameter (limit, state, offset) is fully documented inline, including the next_offset chaining hint. The description contributes no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List payment methods') and enumerates the returned domain values (cash, card, transfer, credit) plus the id field. The resource is distinct enough from siblings like bsale_list_payments and bsale_list_document_types that an agent can pick it without opening the schema, though it never explicitly contrasts with them.

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

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

'The id is needed to record a payment' gives a clear downstream use case that implies the sequence with bsale_create_payment. It stops short of explicit when-not guidance or naming the alternative tool directly.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's added value is the disclosure of what comes back: net vs. taxed price per variant plus the detail id. It also discloses the underlying endpoint, which helps an agent understand it is an unauthenticated-scope-dependent REST read. It does not mention rate limits or whether expand affects payload size.

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 compact sentences front-loaded with return content, then filters, then the endpoint. Each sentence carries information; the trailing URL is marginally useful for API-literate agents but not 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 read-only list tool with no output schema, the description covers the key return fields, the filter options, and the downstream use of the detail id. Gaps are `expand` behavior and pagination expectations, but the schema documents limit/offset and next_offset adequately.

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 43%, so the description partially compensates by mapping three filters (SKU code, barcode, variant id) to their parameters, which is more than the schema's bare type declarations. But `price_list_id`, `expand`, and the pagination semantics are left entirely to the schema, and `expand` — the most ambiguous parameter — is undocumented anywhere.

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

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

The description names the resource precisely ('Prices in one price list') and enumerates what is returned: net price (variantValue), price with taxes, and the detail id. This is distinctly a detail-level read, separable from bsale_list_price_lists, though no sibling is named 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?

'Filter by variant id, SKU code or barcode' gives concrete narrowing context, and 'the detail id needed to change a price' implicitly positions this as the precursor to bsale_update_price. However, no alternative tool is named and there is no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the GET endpoint plus the shape of the returned fields, but says nothing about auth requirements, rate limits, or default result cardinality beyond what the schema states.

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

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

Three short sentences: what it lists, the follow-up tool, and the endpoint. No filler, and the content most needed for selection (the resource and the sibling reference) comes first.

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

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

For a read-only listing tool with no output schema, the description tells the agent the key returned fields and how to continue to details. Only the undocumented expand and coin_id parameters leave a minor gap, which the schema's limits partially offset.

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%: limit and offset are documented in the schema, but expand and coin_id have no description anywhere. The mention of 'currency' hints at coin_id but doesn't state that it filters, and 'expand' is entirely unexplained, so the description only partially compensates for the coverage 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?

States a specific verb and resource ('List price lists') plus the fields surfaced (name, currency, state), so the agent knows exactly what this returns. It also names the sibling bsale_list_price_list_details as the place to take an id, which distinguishes it from the detail endpoint.

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 list-then-detail workflow by saying 'Use the id with bsale_list_price_list_details', which is a useful handoff. However, it gives no explicit when-to-use condition, no exclusions, and no mention of paging behavior, so usage is largely inferred.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /v1/products.json) and the data-model caveat that SKUs live on variants, but says nothing about result size limits, rate limiting, or what a page actually contains.

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

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

Two sentences plus the endpoint, front-loaded with the resource and its fields, then the sibling pointer. Every clause carries information; nothing is redundant with the title.

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

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

For a read-only list tool with no output schema, the description covers identity, scope and the key sibling relationship. Remaining gaps are the meaning of the expand parameter and what a returned page looks like, which the description leaves entirely to the schema.

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

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

Schema coverage is 67%, so limit, state, offset and classification are already documented in the schema, including the 'pass the previous reply's next_offset' paging hint. The description adds nothing for the two undocumented parameters, expand and product_type_id, which are the ones most needing explanation.

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

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

States a specific verb and resource ('List products and services') and enumerates the fields returned (name, description, class, stock control, state). It also pre-empts the most likely confusion by pointing SKU lookups to bsale_list_variants, so an agent can distinguish it from the sibling without opening the schema.

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?

Explicitly routes SKU-related needs to bsale_list_variants, which is the main alternative an agent would consider. It does not address when to prefer bsale_get_product for a single record, but the list-vs-get split is largely self-evident from the verb.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that credit notes and reference documents are only present with expand, which is genuine behavioral context, but it says nothing about pagination flow, rate limits, or total counts.

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 resource and its returned fields, followed by the actionable expand tip. The trailing GET endpoint adds little for an MCP caller but costs only a clause.

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

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

With only three optional params and no output schema, the description's field enumeration plus the expand values are enough to call the tool correctly. A note on what offset/next_offset paging looks like in the reply would close the remaining gap, but the schema already carries next_offset 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?

Limit and offset are documented in the schema, but expand has no description and no enum, so the description's 'expand=[reference_document,credit_note,details]' supplies the exact allowed values an agent would otherwise have to guess. That is meaningful compensation for the 67% schema coverage 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?

States a specific verb and resource ('List returns (devoluciones)') and enumerates the payload fields (date, motive, amounts, credit note), which is more than the title alone conveys. It doesn't explicitly contrast with siblings like bsale_list_documents or bsale_list_payments, but 'returns' is a distinct enough resource that an agent can route to it.

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

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

There is no explicit when-to-use or when-not guidance, and no alternative tool is named despite many list-shaped siblings. The implicit usage (list return records) is obvious, and the expand hint gives partial operational guidance, but alternatives are 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=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond them by enumerating the returned measures (quantity, reserved, available), explaining that expand=[variant,office] enriches with names, and disclosing the pack-filtering caveat.

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 dense sentences with no filler: returned fields first, then filter options, then the expand modifier and endpoint. Every clause carries actionable information and the payload 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 7-parameter read tool with no required params and no output schema, the description covers what is returned, how to filter, and how to expand relations — enough to call it correctly. It leaves default sorting and the no-filter fallback unstated, but those are minor.

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

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

Schema description coverage is only 43%, and the four undocumented parameters (code/barcode/office_id/variant_id) are all explained in prose, including the non-obvious pack interaction between variant_id and office_id. The remaining gap is limit/offset, which the schema already documents.

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 resource and its granularity (stock per variant and office) plus the exact fields returned (quantity, reserved, available), so an agent can immediately separate it from bsale_list_variants or bsale_list_products. It also pins the underlying endpoint, GET /v1/stocks.json.

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 supported filter dimensions (office, variant id, SKU code, barcode) and gives a concrete conditional rule: for a pack, pass a variant filter plus office_id. That is real when-to-use guidance, though it never names an alternative sibling or a when-not condition.

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 cover the safety profile (readOnly, non-destructive, open-world), so the description's main addition is the endpoint path and the returned fields. It says nothing about pagination behavior, default page size, or that results are state-filterable, which an agent listing many users would want to know.

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

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

Two compact sentences, front-loaded with the purpose. The trailing endpoint path is mild filler but cheap and occasionally useful for debugging.

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 five-parameter list tool with no output schema, the description tells the agent what fields come back, which is genuinely useful. But it omits the paging contract and filtering options that determine correct invocation, leaving gaps the schema only partially fills.

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 60% and the description contributes zero parameter meaning: it never mentions limit/offset paging, the state filter, office_id scoping, or expand. The two undocumented params (expand, office_id) are left entirely unexplained anywhere.

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

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

States a specific verb and resource ('List Bsale users') and disambiguates the resource as sellers/cashiers, plus what fields come back (name, office). No explicit differentiation from the nearest sibling bsale_user_sales_summary, but the resource noun is distinctive enough.

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

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

No when-to-use guidance, no prerequisites, no mention of how it relates to bsale_user_sales_summary or bsale_list_offices, despite office_id being a filter. The agent must infer that this is a plain roster lookup.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the concrete endpoint (GET /v1/variants.json) and the returned field set, which is useful, but it says nothing about result caps, pagination behavior, or the meaning of 'stock settings' that isn't already in the 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 short sentences, front-loaded with the resource and its returned fields, followed by the filter options and the endpoint. The raw endpoint path adds little for an agent but costs only a clause; nothing else is padding.

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

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

With no output schema, the description takes on the job of enumerating return fields, and it does so. Pagination is handled in the schema via limit/offset and the 'next_offset' hint, so the remaining gap is the undocumented 'expand' parameter rather than any structural omission.

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

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

The description names four filter dimensions (SKU code, barcode, description, product id), which supplies meaning for 'barcode' and 'product_id' that the schema leaves completely undocumented. It does not address 'expand', 'state', or the pagination params, but those carry schema descriptions, so coverage at 63% is adequately compensated.

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

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

States a specific verb and resource ('List product variants, the sellable SKUs') and immediately enumerates what a variant carries (description, SKU code, barcode, stock settings, product link), which distinguishes it from bsale_list_products (product level) and bsale_get_variant (single record). An agent can tell what this returns without opening the schema.

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 says how to narrow results ('Search by SKU code, barcode, description or product id'), implying this is the lookup tool for finding a variant when you don't know its id. However, it never explicitly contrasts itself with bsale_list_products or bsale_get_variant, and gives no when-not guidance, leaving the routing decision partly 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=true, destructiveHint=false, so safety needs no restatement. The description adds the grouping semantics and endpoint path, but says nothing about pagination behavior or how the grouped rows are shaped, which matters for a summary call.

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

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

One dense sentence carries the aggregation definition, then the alternative mode, then the example question. No filler, and the core 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?

No output schema exists, and the description does name the returned measures (net, tax, total, count), which is the key missing piece for an agent. Coverage is only slightly short on response shape per grouping and pagination, both partly handled by schema 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?

Schema coverage is 100%, so limit/offset/code_sii/emitted_from/emitted_to are fully documented there. The description's only parameter gloss ('set per_document to list each document instead') largely restates the schema's own wording, so it adds little beyond the baseline.

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

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

States a concrete verb and resource ('Totals of sales documents') plus the exact aggregation dimensions (net, tax, total, count; by month, document type, office). Clearly distinguished from bsale_list_documents by the aggregation framing and the per_document escape hatch.

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?

Gives an explicit use case ('how much did we sell in September?') and the condition for the alternative shape (set per_document to list each document instead). It does not mention the closest sibling, bsale_user_sales_summary, which is the main remaining routing ambiguity.

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 disclose that this is a destructive, idempotent write operation. The description adds important behavioral context beyond annotations: only supplied fields are sent, and those values overwrite stored values, which clarifies partial-update semantics.

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

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

The description is three compact sentences with zero waste. It front-loads the operation type and essential mutation semantics.

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 13-parameter mutation with no output schema and low schema description coverage, the description covers the core update behavior, overwrite semantics, and endpoint. It still omits how to clear fields, validation or error behavior, permission requirements, and most parameter meanings.

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

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

There are 13 parameters but only 31% schema description coverage, and the description provides no field-level guidance. The sentence 'only the fields you pass are sent' helps explain optionality generally, but it does not compensate for undocumented parameters such as first_name, last_name, phone, address, and others.

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

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

The description gives a specific verb and resource: 'change fields of an existing customer.' The word 'existing' distinguishes it from bsale_create_client, and the PUT endpoint reinforces that this is an update operation.

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

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

The description implies when to use it by saying 'change fields of an existing customer,' and the partial-update note is useful context. However, it does not explicitly state when to choose this over bsale_create_client or how to handle missing fields.

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 write/destructive/idempotent, so the bar is lower; the description adds real context by explaining the impact ('changes what Bsale charges on new sales') and clarifying the price is tax-exclusive. It doesn't mention permission or reversal semantics, keeping it at 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?

Front-loads 'WRITE:' then the operation, impact, prerequisite, and endpoint in three tight sentences with no waste.

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 3-param mutation with no output schema and safety covered by annotations, the description supplies the mutation subject, impact, prerequisite, and endpoint. It is essentially complete, with only a minor gap on price_list_id 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?

The description clarifies net_price is tax-exclusive and directs where detail_id comes from, adding meaning beyond the 67%-covered schema. price_list_id is left to the URL pattern rather than described, so not a perfect 5.

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

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

States a specific verb and resource: 'set the net price ... of one variant in a price list'. It distinguishes the operation clearly from sibling reads and other update tools, and even names the exact field (variantValue) being changed.

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

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

Explicitly routes the agent to bsale_list_price_list_details to obtain detail_id, which is the key prerequisite. It does not discuss when-not-to-use or alternatives for the update itself, but the operational 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new behavioral detail: the default reporting window is today in UTC and results are aggregated per seller rather than returned as raw documents.

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

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

A single sentence that front-loads the resource and scope, with the default window and endpoint appended compactly. No filler and nothing that could be cut without losing information.

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

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

For a read-only, three-parameter aggregation endpoint with no output schema, the description covers scope, grouping, defaults, and the filtering option. A brief note on the shape of the returned totals would be the only useful addition.

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 67% and the two undocumented aspects are covered by the description: 'default: today, UTC' explains what happens when from/to are omitted, and 'or for one user' gives user_id its meaning (filter results to a single seller), which the schema leaves bare.

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 resource and verb: 'Sales and tax subtotal per seller' over a date range or for one user, plus the underlying endpoint. It is distinguishable from the sibling bsale_sales_summary by its per-seller grouping, though it never names that sibling explicitly.

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

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

The description implies usage through the two modes (date range vs. single user) and gives the default range of today (UTC), but it never states when to reach for this over bsale_sales_summary or what to do if both from and to are omitted together. Usage is inferable, not spelled out.

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