TOConline MCP by usefulapi

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context beyond that: it returns JSON:API data and relationships and maps to GET /api/customers/{id}. It does not cover not-found behavior or error semantics, but for a simple read tool the added disclosure is meaningful.

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

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

Three short sentences, front-loaded with the core action and scope. The return behavior and endpoint are tacked on without redundancy or wasted words.

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-record read with one required parameter, readOnly annotations, and no output schema, the description gives enough to call it correctly. It mentions the returned JSON:API shape and endpoint; the main missing piece is error/not-found handling, which is minor 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 0%, so the description needs to carry parameter meaning. It identifies the id as a numeric record id, which is somewhat helpful, but the schema pattern already enforces digits and the description does not explain where the id comes from or how it relates to customer identity.

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 TOConline customer') and clarifies retrieval by numeric record id. It implicitly separates itself from the list endpoint by saying 'one', but it does not name toconline_list_customers or other siblings explicitly.

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

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

Usage is implied: use this when you already have a customer record id and need a single customer. There is no explicit guidance on when to choose this over toconline_list_customers, nor any stated prerequisites or 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, so the safety profile is covered. The description adds genuinely new behavioral context: the return shape ('JSON:API data and relationships') and the underlying endpoint (GET /api/commercial_purchases_payments/{id}), which tells the agent what to expect back.

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

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

Three short sentences, front-loaded with the core action and free of filler. The endpoint sentence is somewhat redundant with the name but is compact enough to earn its place for an API-mapping agent.

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 with no output schema, the description covers the operation, the id semantics, and the return envelope. Nothing essential is missing, though a note on error behavior for unknown ids would complete it.

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

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

Schema coverage is 0%, but with a single required parameter the burden is light. The description clarifies that id is a numeric record id, which adds a little meaning, but the regex pattern in the schema already enforces the numeric format and no further guidance (e.g. where ids come from) is given.

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 ('Read') and resource ('purchase payment') and scopes it to a single record by numeric id, which distinguishes it from the list_* siblings by implication. It does not explicitly name toconline_list_purchase_payments as the way to obtain ids, but the singular read is unambiguous.

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

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

The phrase 'by numeric record id' implies this is used after you already have an id, but the description never states when to prefer this over the list endpoint or how to get an id in the first place. Usage is inferable rather than stated.

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

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

The readOnlyHint annotation already establishes the safety profile. The description adds useful context about the return shape ('JSON:API data and relationships') and the underlying endpoint, but does not mention error behavior, authorization needs, or what happens if the id is not found.

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 what the tool does and its return value. Every sentence contributes useful information 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 simple one-parameter read tool with no output schema, the description covers the action, resource, id semantics, return format, and endpoint. It could be stronger with a note on not-found behavior, but it is largely complete.

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

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

Schema description coverage is 0%, so the description must compensate. It adds that the id is a 'numeric record id', which clarifies the otherwise opaque string pattern, but it does not explain where to obtain the id or any further format constraints.

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 ('Read') and resource ('one TOConline sales document') and clarifies it is by numeric record id. It implicitly distinguishes from the list sibling by saying 'one', though it does not name the alternative.

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 'Read one ... by numeric record id', but there is no explicit guidance on when to use this versus toconline_list_sales_documents or other retrieval tools. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real value beyond that by disclosing the return shape (JSON:API data and relationships) and the underlying GET endpoint. It does not mention error behavior for missing ids, which keeps it short of a 5.

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

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

Three short sentences, front-loaded with the verb and resource. The endpoint citation is slightly redundant but still useful for traceability and does not bloat the 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?

With no output schema, the description steps in to describe the return value as JSON:API data plus relationships, which is exactly the missing piece. For a one-param read tool it is nearly complete, lacking only failure-mode 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?

The single parameter has the same name as its schema field with 0% description coverage, so the description must compensate. It adds that the id is 'numeric' and identifies a specific record, but omits any format or length detail beyond what the schema pattern already enforces.

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 (read) and resource (TOConline sales receipt), scoped to a single record by id, which cleanly separates it from the sibling toconline_list_sales_receipts. The underlying endpoint is even cited, 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 phrase 'Read one ... by numeric record id' implies this is the single-record counterpart to the list tool, but no sibling is named and there is no explicit when-to-use or when-not guidance. Usage is inferable from the contrast with list_sales_receipts rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's 'Read' adds little beyond it. It does add that the response is JSON:API data and relationships, which is modest useful context, but there is no mention of error behavior for a missing or invalid id.

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 action and resource, followed by return shape and endpoint. No wasted words.

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 with no output schema, the description covers purpose, the return shape (JSON:API data and relationships), and the endpoint. It is close to complete, lacking only guidance on obtaining the id or error handling.

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 does some work by calling out 'numeric record id'. However, the schema's pattern ^[0-9]{1,20}$ already enforces numeric-only, and the description doesn't add meaning such as where the id comes from.

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 (Read), resource (TOConline supplier), and cardinality (one, by numeric record id), and the endpoint GET /api/suppliers/{id} confirms scope. It is clearly distinguishable from the sibling toconline_list_suppliers.

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 ... supplier by numeric record id' implies single-record retrieval versus the list sibling, giving clear usage context. It does not explicitly say to use toconline_list_suppliers to find an id first, nor state 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, so the sentence 'Read-only' is largely redundant. However, the description adds real value by disclosing the return shape — vendor JSON:API data with attributes, relationships and pagination metadata — which matters because no output schema exists. The underlying endpoint (GET /api/countries) is also 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?

Three short sentences, front-loaded with the purpose and followed by return shape and endpoint. The 'Read-only.' fragment restates an annotation and is the only wasted clause; otherwise there is no padding.

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

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

For a simple read-only list with zero required parameters, the description plus a fully documented schema is nearly sufficient, and the return-shape sentence compensates for the missing output schema. Minor gap: the filters example values reference customers, products and documents rather than countries, leaving the resource's filterable fields unstated.

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

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

Schema description coverage is 100%, so page, page_size and filters are already fully documented in the schema. The description's mention of 'pagination metadata' only loosely gestures at the paging parameters and adds no syntax or behavioral detail (e.g., how filters behave for countries specifically). 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 the connected TOConline company's countries'), which is unambiguous against siblings such as list_currencies or list_customers because the resource noun differs. It does not explicitly contrast with any sibling, but none share the same resource, so differentiation is achieved by the resource name alone.

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 statement of when to use this tool versus alternatives, no preconditions, and no exclusions. The only implicit guidance is that results are scoped to the 'connected' company, which an agent must infer.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces read-only behavior while adding useful context: the vendor's JSON:API return shape, attributes, relationships, pagination metadata, and the underlying endpoint. It does not mention auth or rate limits, but the return-shape disclosure is valuable beyond annotations.

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

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

The description is three short sentences with no wasted text. The primary purpose is front-loaded, followed by return behavior and endpoint detail.

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

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

For a simple, parameter-light list tool with no output schema, the description provides enough context about what is returned and how the result is structured. It could be slightly more complete by mentioning permissions or typical use cases, but the essential information is present.

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

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

Schema description coverage is 100%, and the schema itself documents page, filters, and page_size thoroughly, including examples and constraints. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: list the connected company's currencies. It is clear what the tool does, though it does not explicitly differentiate itself from sibling list tools such as list_countries or list_tax_descriptors.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives, nor does it state any preconditions or exclusions. Usage is only implicit from the resource name.

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

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

Annotations already declare readOnlyHint=true, so 'Read-only' is redundant, but the description adds genuine value by disclosing the return shape (JSON:API data, attributes, relationships, pagination metadata) and the underlying endpoint GET /api/customers. With no output schema present, that return-format disclosure is what carries the read here.

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 purpose, then return shape, then a safety/endpoint note. Nothing is padded and no sentence repeats 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?

With three optional params, nested filters, and no output schema, the description covers the essentials: what is returned and that it is read-only. It could go slightly further by noting pagination traversal or how filtering narrows results, but an agent has enough to invoke 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 description coverage is 100%, and the schema already documents page, page_size (1–100, default 20), and filters with concrete examples and the invalid-field rejection rule. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: 'List the connected TOConline company's customers', which cleanly separates it from the sibling get_customer (retrieval of one) and from list_suppliers/list_products (other resources). It stops short of naming an alternative explicitly, so it lands at 4 rather than 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?

There is no statement of when to use this versus toconline_get_customer, nor any note about paging through results or when filtering is warranted. The only guidance is the implied 'list = many', leaving the agent to infer selection criteria.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description still adds useful behavioral context by disclosing the response shape (JSON:API data, attributes, relationships, pagination metadata) and the exact endpoint. It does not mention rate limits or filter failure behavior, a minor gap.

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

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

Three short sentences with the core purpose front-loaded and no filler. Slight redundancy between 'Read-only' and the surrounding annotation, but it earns its place for agents that read only the description.

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, so the description's note about JSON:API data/attributes/relationships/pagination is exactly what an agent needs to interpret results. Parameters are fully covered by the schema; only filtering semantics specific to series are missing.

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

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

Schema description coverage is 100% with all three params (page, page_size, filters) fully documented in the schema. The description adds no parameter-specific meaning, so baseline 3 applies; notably the filters examples are customer/product/document oriented rather than series-specific.

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

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

States a specific verb (List) and resource (document series) scoped to the connected company, and names the underlying endpoint. It doesn't explicitly contrast with the many sibling list_* tools, but the resource is unambiguous.

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

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

No indication of when to use this versus alternatives like toconline_list_sales_documents, nor any prerequisites or exclusions. The only usage-adjacent text is 'Read-only', which is a safety statement, not selection 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, and the description reinforces that while adding genuine context: it discloses the return shape (JSON:API data, attributes, relationships, pagination metadata) and the underlying endpoint. It does not mention rate limits or error behavior, but for a simple read-only list this is meaningful added value.

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 core purpose, with no filler. Each sentence (purpose, return shape, read-only, endpoint) contributes something, though the read-only note is largely redundant with 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 3-param optional list tool with full schema coverage and a readOnly annotation, the description covers purpose, safety, return shape, and endpoint. Without an output schema it would be nice to know more about the item-family attributes returned, but nothing critical for correct invocation 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 page, filters, and page_size are already well documented in the schema. The description adds only that pagination metadata is returned, not any filter-field semantics specific to item families, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List ... item families') and scopes it to the connected TOConline company, which is enough to distinguish it from get_* siblings. It does not explicitly differentiate itself from other catalog lists such as toconline_list_products or toconline_list_services, so it falls 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?

Usage is implied by the resource name: an agent would call this when it needs the company's item families. There is no explicit statement of when to prefer or avoid it relative to the many sibling list tools, and no prerequisites or exclusions are mentioned.

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

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

readOnlyHint=true is already declared, so the safety profile is covered; the description still adds value by disclosing the JSON:API response shape (attributes, relationships, pagination metadata) and the underlying endpoint GET /api/products. It omits pagination defaults and error behavior, but those live 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 with zero filler; the core purpose is front-loaded and the return-shape and endpoint details follow logically. Every sentence carries 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?

With no output schema, the description usefully characterizes the return payload and notes read-only behavior, and the schema covers all three parameters. Nothing critical is missing for correct invocation, though rate limits or large-result caution would round it out.

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

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

Schema description coverage is 100%, so page, filters, and page_size are already well documented, including filter examples. The description adds nothing about parameters, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('products' of the connected TOConline company'), which is unambiguous against siblings like toconline_list_services or toconline_list_item_families. It does not explicitly name a sibling or contrast scope, so it stops 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?

The description implies usage by scoping to the connected company's products, but gives no when-to-use conditions, no exclusions, and no guidance distinguishing it from resource-adjacent siblings (services, item families). Minimum viable context only.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context by saying the response is JSON:API data with attributes, relationships, and pagination metadata, and it names the underlying endpoint.

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

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

Three short sentences are front-loaded with the core purpose, followed by return-shape and safety/endpoint context. There is no wasted wording.

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 explains the general return shape as JSON:API data with attributes, relationships, and pagination metadata. Combined with complete parameter descriptions and read-only annotations, it is nearly complete, though it could say more about what document fields are returned.

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

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

Schema description coverage is 100%, so page, page_size, and filters are already well documented in the schema. The description adds no parameter-specific detail beyond that, which is acceptable given the full schema coverage.

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

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

The description states a specific verb and resource: it lists the connected TOConline company's purchase documents. The name and text clearly distinguish this from sales documents and purchase payments, though the description itself does not explicitly name those alternatives.

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 says what the tool does but gives no guidance on when to use it versus sibling tools such as toconline_list_purchase_payments or toconline_list_sales_documents. There are no exclusions, prerequisites, or alternative-selection cues.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only.' and adds useful context beyond annotations: the underlying endpoint (GET /api/commercial_purchases_payments) and the shape of returned data (JSON:API data, attributes, relationships, pagination metadata).

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, purpose first, then return shape, then read-only/endpoint note. Nothing is wasted and the key information is front-loaded.

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

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

For a simple read-only list tool with full schema coverage, the description covers purpose, return format, and safety, which is sufficient. It lacks explicit pagination behavior guidance and filter examples that would make it fully complete.

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

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

Schema description coverage is 100%, so page, page_size, and filters are already well documented in the schema. The description adds nothing about parameter usage, so the baseline 3 applies.

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

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

The description states a specific verb ('List') and resource ('purchase payments') scoped to the connected company, which is unambiguous. It does not explicitly contrast with the sibling toconline_get_purchase_payment, but the list-vs-get distinction is inferable from the verb.

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

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

No guidance on when to use this versus toconline_get_purchase_payment or how to narrow results with filters. The agent is left to infer usage context entirely.

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

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

The readOnlyHint annotation already establishes safety, and the description reinforces this with 'No documents are changed or finalized.' However, it does not disclose pagination behavior, ordering, or what a line item contains beyond the bare endpoint.

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

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

Three short, front-loaded sentences with no wasted words. The endpoint is placed after the purpose statement, and the safety clarification follows logically.

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 annotations covering safety, the description is mostly adequate. But with no output schema and no explanation of return values, the agent is left guessing what fields a line item includes and whether pagination metadata is returned.

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%: page and page_size are documented in the schema, but document_id has no description. The phrase 'of a sales document' implies document_id is a sales document identifier, which adds marginal meaning beyond the schema.

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

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

States a specific verb and resource: 'Read all line items of a sales document.' This clearly distinguishes it from sibling tools like get_sales_document (document header) and list_sales_documents (document list).

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 name and description imply when to use it, but there is no explicit guidance on when to choose this tool versus get_sales_document or how to obtain the required document_id. 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, so the safety profile is covered. The description adds value by disclosing the return shape (JSON:API data, attributes, relationships, pagination metadata) and the concrete endpoint, which goes 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 short sentences, front-loaded with the purpose and return shape, with no wasted text. Efficient and easy to parse.

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 summarizing the JSON:API return structure and pagination metadata. For a read-only list tool with fully documented params, this is nearly complete, though it could note filter-field constraints more explicitly.

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

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

Schema description coverage is 100%, so page, page_size, and filters are fully documented in the schema. The description adds no parameter-level detail beyond that, making the baseline 3 appropriate.

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

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

The description uses a specific verb+resource ('List ... sales documents') scoped to the connected company and names the underlying endpoint. It distinguishes at a high level from singular siblings like toconline_get_sales_document, but doesn't explicitly contrast 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 read-only/list nature implies when to use it, but there is no explicit guidance on when to choose this over toconline_get_sales_document or toconline_list_sales_document_lines. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces it with 'Read-only' plus the concrete endpoint GET /api/commercial_sales_receipts. It also discloses the response envelope (JSON:API data, attributes, relationships, pagination metadata), which annotations do not cover.

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 what the tool does, followed by return shape and read-only/endpoint facts. No filler or repetition.

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

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

With no output schema, the description compensates by sketching the return structure (JSON:API data, attributes, relationships, pagination) and the endpoint. It stops short of describing error behavior or filter-mismatch handling, but is otherwise sufficient to call the 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?

Schema coverage is 100%, so page, page_size and filters are fully documented in the schema itself. The description adds no parameter-level detail beyond mentioning pagination metadata, 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?

Specific verb ('List') + resource ('sales receipts') scoped to the connected TOConline company, which cleanly separates it from the singular toconline_get_sales_receipt sibling. It does not explicitly name competing list tools (e.g. toconline_list_sales_documents) but the resource is unambiguous.

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

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

No statement of when to use this versus alternatives such as toconline_get_sales_receipt for a single record or toconline_list_sales_documents. Usage must be inferred entirely from the verb 'List'; no exclusions or prerequisites are given.

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

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

With no output schema, the sentence describing the return payload (JSON:API data, attributes, relationships, pagination metadata) is genuinely valuable context the agent could not otherwise know. 'Read-only' and the GET path largely restate the readOnlyHint annotation, and nothing is said about auth scope or rate limits, so it stops short of a 5.

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 purpose and followed by return shape then the endpoint. 'Read-only.' duplicates the readOnlyHint annotation and the GET path is redundant with the endpoint, so there is a little waste but no structural problem.

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-parameter list tool with a nested filters object and no output schema, the description covers purpose and return shape adequately while the schema carries full parameter detail. Missing only explicit guidance on filter usage and result volume.

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

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

Schema description coverage is 100% and the schema itself documents page, page_size (1–100, default 20) and filters with concrete examples per resource. The description adds no parameter meaning of its own, 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 the connected TOConline company's services') and names the endpoint GET /api/services. The resource noun 'services' distinguishes it from the many sibling list_* tools (products, customers, suppliers), though it never says so 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?

There is no guidance on when to use this tool versus alternatives such as toconline_list_products or toconline_list_item_families, and no advice on when pagination or filters matter. Usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful context: it returns JSON:API data, attributes, relationships, and pagination metadata, and identifies the underlying GET /api/suppliers endpoint. It does not cover pagination defaults or error behavior, but for a read-only list tool this is solid additional disclosure.

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

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

The description is short and front-loaded with the purpose. 'Read-only' partially repeats the annotation and the endpoint line is somewhat redundant, but there is no filler and every sentence contributes to understanding.

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 notes that the response includes JSON:API data, attributes, relationships, and pagination metadata. Combined with the complete input schema and read-only annotation, an agent has enough to call it correctly, though supplier-specific filter examples are 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 description coverage is 100%, so the schema already documents page, filters, and page_size in detail. The description adds no parameter-specific meaning beyond what is in the schema, which is the baseline 3 when schema coverage is complete.

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 the connected TOConline company's suppliers.' The plural 'List' and resource 'suppliers' clearly distinguish it from the sibling toconline_get_supplier, which retrieves a single supplier.

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 bulk retrieval of suppliers, but it does not explicitly say when to use this tool versus toconline_get_supplier or when to apply filters. Usage is inferable from the name and resource 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, so 'Read-only' repeats structured data. The description does add value by disclosing the return shape (JSON:API data, attributes, relationships, pagination metadata) and the underlying endpoint, but since there is no output schema this is thin behavioral context — no rate limits, error behavior, or result-size guidance.

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 purpose and followed by return shape and read-only/endpoint notes. No filler, though the 'Read-only. GET /api/tax_descriptors.' pair is somewhat redundant with the annotation.

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 fully documented parameters and no output schema, the description supplies the return structure and access method an agent needs. It could go further by indicating what a tax descriptor contains or which fields are commonly filtered, but 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 page, page_size, and the filters object are already fully documented, including filter syntax and rejection of invalid fields. The description adds nothing about parameters, which is acceptable at full schema coverage but constitutes only baseline value.

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

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

The description states a specific verb and resource ('List ... tax descriptors') scoped to the connected TOConline company, which is enough to distinguish it from the many sibling list_* tools by resource name. It stops short of explicitly contrasting with any sibling, but the resource specificity makes misselection unlikely.

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

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

Usage is only implied by the resource name: an agent infers this is the tool to fetch tax-descriptor reference data. There is no statement of when to prefer it, no prerequisites, and no mention of alternative tools or when not 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 only declare readOnlyHint, and the description usefully adds the return shape (JSON:API data, attributes, relationships, pagination metadata) and the exact HTTP endpoint — beyond what the annotation provides. It does not state whether the call enumerates all pages or what an error from TOConline looks like, which keeps it off a 5.

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: purpose, return shape, access mode plus endpoint. Front-loaded and every sentence carries information; nothing is repeated filler.

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

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

With no output schema, the description correctly compensates by sketching the JSON:API response envelope and pagination metadata, and confirms read-only access. Missing only secondary detail such as default listing behavior or pagination traversal, so slightly short of complete.

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

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

Schema description coverage is 100%, with page, page_size and the nested filters object fully documented including examples and the note that invalid field names are rejected. The description adds no parameter meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List ... units of measure') scoped to the connected TOConline company, plus the underlying endpoint GET /api/units_of_measure. The resource is unambiguous against siblings such as toconline_list_currencies or toconline_list_products, so an agent can route correctly without opening a 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?

Usage is only implied: as a 'List' tool with no required parameters it is evidently a bulk enumeration call for the vendor's units of measure. There is no explicit when-to-use vs alternatives, no guidance on when filtering by page_size or filters matters, and no stated prerequisites.

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