Precoro MCP by usefulapi

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

Announces WRITE, states irreversibility ('Cannot be undone through this server'), discloses the permission precondition, and explains downstream consequences (PO sent to supplier, invoice to payment). This adds real value beyond the destructive/readOnly annotations. Doesn't detail rate limits or the exact response, so not 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?

Front-loads 'WRITE:' and packs prerequisite, side effects, discovery path, irreversibility, and endpoint into 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?

Covers the important behavioral context (permission requirement, spending release, irreversibility) needed to call a mutation tool safely. No output schema exists, so return values needn't be explained; remaining gaps 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 coverage is 100%, so the schema already documents both parameters (idn as company document number, document as enum). The description adds no format or syntax details beyond it, making baseline 3 correct.

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 (approve) and resource (document), with the wire endpoint POST /{document}/{idn}/approve. It is clearly distinguishable from reject_document and submit_document siblings.

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

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

Tells the agent where to find candidates ('list tools and waiting_for_my_approval') and states the precondition (user must be a current approver). It doesn't explicitly route to reject_document/submit_document for the alternative decision, so not a full 5.

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

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

Adds substantial context beyond the annotations: draft/open state, the approval lifecycle dependency, the exact endpoint, and the returned identifiers (idn and id). This is meaningful detail even though annotations already declare readOnlyHint=false and destructiveHint=true.

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-loaded with the 'WRITE:' marker and the draft-status outcome, with no filler sentences. It is dense and parenthetical-heavy, but every clause carries actionable 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?

Despite no output schema, the description states the return values (idn and id) and fully enumerates the required inputs and their sources. An agent could call this correctly without further exploration.

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

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

The description adds real meaning the schema cannot express: the item line accepts either a catalog item_id or a name with quantity and price, and all required document custom fields must be supplied in custom_fields. It does not mention budget_id, legal_entity_id, note, or supplier_id, though the schema covers those at 75% 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?

Opens with 'WRITE: create a purchase requisition in draft (open) status', giving an explicit verb, resource, and resulting state. It immediately distinguishes itself from precoro_submit_document by saying the document is not submitted for approval until that tool is called.

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

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

Clearly states when to use this tool (creating a draft) and what to do next (call precoro_submit_document to submit). It also routes the agent to the correct helper tools for resolving ids (precoro_list_reference_data, precoro_list_items), which no schema field conveys.

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 it is a non-idempotent, destructive, open-world write; the description adds substantive behavior beyond that — uniqueness collisions are rejected, the record is shared across all legal entities, and the new supplier may sit in a pending-approval state before it is usable. It omits what happens on partial failure and does not explain why destructiveHint is set for a create.

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 plus the endpoint line, front-loaded with the operation type and followed by constraints in diminishing importance. Every sentence carries a distinct fact 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?

Covers the mutation's preconditions, sharing scope and approval caveat, but with 14 parameters, 36% schema coverage and no output schema, the description never says what the returned supplier contains or how to detect the pending-approval state. Adequate for the write itself, thin for the data contract.

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 36% across 14 parameters, so the description needs to compensate and largely does not: it only touches the name/uniqueness rule, leaving contacts, currencies, conditions, minimum_order_sum, delivery_period_days and address fields undocumented in both places. An agent must guess at validation and formatting rules for most inputs.

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+resource ('WRITE: create a supplier') and names the exact endpoint (POST /suppliers). The verb alone separates it from the get_/list_ siblings, so no ambiguity remains 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?

Gives real usage context: name must be unique in the company and a duplicate name, unique code or registration number is rejected, plus the caveat that approval settings may block use on orders. It does not point at an alternative (e.g. look up an existing supplier with precoro_get_supplier before creating), so it stops short of explicit when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful payload context — that the response includes items, custom fields, and approval steps — which is not in the schema or annotations. It stops short of noting auth requirements or rate limits, keeping it from 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?

Two compact sentences, front-loaded with the resource and scope, followed by the endpoint. Every phrase earns its place, and there is 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 single-record read tool with full schema coverage and safety annotations, this is nearly complete: it identifies what is returned (items, custom fields, approval steps) even though no output schema exists. A little more on response shape or error behavior would close the remaining gap.

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

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

Schema description coverage is 100% and the schema already explains that IDN is the company's own document number, not the internal id. The description only repeats 'by IDN' and adds no format or edge-case 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 resource (an expense document) and scope ('one ... by IDN'), which cleanly distinguishes it from the sibling precoro_list_expenses without needing to name it. An agent can immediately tell this is the single-record fetch.

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 when-to-use or when-not-to-use guidance and never mentions the list alternative (precoro_list_expenses) or any prerequisites. The only hint is the implied need for an IDN, which is too thin to count as routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's main added value is disclosing the shape of the response: items, taxes, PO and receipt matching, and payments. It also usefully notes that the same endpoint serves credit notes, which an agent would otherwise not assume. It omits error/not-found behavior, which keeps it below 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?

Two compact fragments with the resource and IDN scoping front-loaded, and no filler. The trailing 'GET /invoices/{idn}' duplicates information already implied by the tool name, a minor redundancy, but overall the text is tight and scannable.

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 a single fully documented parameter, no output schema, and annotations covering safety, the description does the one thing that matters: it summarizes what the agent will actually receive (line items, taxes, matched POs/receipts, payments). A note on lookup failure or on the credit-note IDN namespace would make it 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% and the schema already explains that IDN is the company's own document number rather than the internal id. The description only restates 'by IDN' without adding format, source, or failure semantics. Baseline 3 is correct when the schema does the explanatory work.

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 ('One supplier invoice or credit note by IDN') and enumerates the payload contents (items, taxes, PO/receipt matching, payments). The 'One ... by IDN' framing implicitly separates it from precoro_list_invoices, though the sibling is never named. The added 'GET /invoices/{idn}' endpoint line anchors the resource unambiguously.

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

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

Usage is only implied: an agent can infer you call this when you already hold a document IDN and need detail, versus precoro_list_invoices for browsing. There is no explicit when-to-use/when-not statement, no mention of behavior when the IDN is unknown, and no guidance on obtaining an IDN in the first place.

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 only the REST endpoint hint (GET /items/{id}), which marginally reinforces that this is a plain read, but says nothing about not-found behavior or what the item contains.

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

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

Two short fragments with zero filler, and the resource is front-loaded. It is arguably over-trimmed for a tool that has no output schema, but nothing is wasted.

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

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

For a one-parameter read tool with annotations covering safety, the description is minimally sufficient. However, since there is no output schema, the agent is left with no indication of what fields a catalog item returns or how to handle a missing id.

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

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

Schema description coverage is 100% and the single 'id' parameter is fully documented in the schema, so the baseline is 3. The description only restates that lookup is by id and adds no format, range, or sourcing detail beyond the schema.

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

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

The fragment 'One catalog item by id' names the resource (catalog item) and the retrieval mode (single item, keyed by id), which is specific enough for an agent to act on. It does not explicitly distinguish itself from the sibling precoro_list_items, but the singular 'one ... by id' implies the distinction.

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

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

Usage is only implied: use this when you already have a single item id. No alternative is named (precoro_list_items would be the obvious fallback for lookup or browsing), and there is no guidance on what to do when the id is unknown.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by enumerating exactly which sub-resources are included in the response (taxes, approval steps, receiving and payment status), which tells the agent not to make follow-up calls. No mention of error behavior for a missing IDN, so not 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?

Two compact sentences, front-loaded with the core action and the returned fields, with the endpoint as trailing technical reference. 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 tool with full schema coverage and no output schema, the description is nearly sufficient: the returned contents are enumerated, filling the gap left by the missing output schema. It does not cover not-found behavior, which is the only notable 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?

Schema description coverage is 100% and the idn parameter is fully documented in the schema, including the 'not the internal id' distinction. The description adds nothing beyond saying 'by IDN', 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 ('Get a purchase order'), scopes it to a single record by IDN, and enumerates the payload (items, taxes, custom fields, approval steps, receiving and payment status). This clearly distinguishes it from precoro_list_purchase_orders.

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 purchase order by IDN' implies single-record retrieval versus the list sibling, but the description never explicitly states when to use this instead of precoro_list_purchase_orders or what happens if the IDN is unknown. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the payload includes items, custom fields and approval steps, which is genuinely useful context beyond annotations, but it says nothing about permissions, rate limits, or error behavior for a missing IDN.

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

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

Two compact sentences with zero filler, front-loaded with the resource and identifier, followed by the endpoint reference. Every clause carries information an agent can act on.

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

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

For a one-parameter read tool with no output schema, the description adequately compensates by enumerating the returned sections (items, custom fields, approval steps). It falls short only on failure modes and whether the IDN must match exactly.

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

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

Schema coverage is 100% and the schema itself explains that idn is the company's own document number, not the internal id. The description only restates "by IDN" and adds no format, casing, or lookup-failure guidance beyond the schema.

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

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

The description names a specific verb and resource ("One purchase requisition by IDN") and lists the embedded content returned (items, custom fields, approval steps). The singular "one ... by IDN" implicitly contrasts with precoro_list_purchase_requisitions, 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?

Usage is only implied: fetch a single requisition when you have its IDN. There is no explicit when-to-use/when-not-to-use guidance and no mention of alternatives such as the list tool or other document getters (invoice, purchase order).

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 return-content context (items and approval steps included) and the underlying endpoint, which is useful given there is no output schema.

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

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

Two short clauses with zero filler; the scope definition is front-loaded and the endpoint is a compact supplementary 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 single-parameter read tool with annotations covering the safety profile, the description is nearly sufficient. Only minor gaps remain, such as error behavior for unknown IDNs, which are not essential to 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 description coverage is 100% and the idn parameter is thoroughly documented in the schema (company's own document number, not internal id). The description adds nothing beyond the schema, so the baseline 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: fetches a single goods receipt by its IDN, and notes it returns items and approval steps. It implicitly contrasts with precoro_list_receipts ("One goods receipt") but does not name 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?

Usage is implied: use when you have a document IDN and want the full record. There is no explicit statement of when not to use it or that listing/search should come first to obtain the IDN.

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

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

Annotations already establish that this is a read-only, non-destructive operation, so the description adds useful context by naming the returned sections and explicitly stating that bank details are never returned. It stops short of describing not-found behavior or access requirements.

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 the core action and return contents, followed by an important exclusion and the endpoint. There is no wasted text.

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

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

For a simple read-only lookup with no output schema, the description is nearly complete because it summarizes the returned fields and the major exclusion. It could mention not-found or empty behavior, but those gaps 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 coverage is 100%, and the schema already explains that the id is numeric rather than the unique code. The description adds no syntax or format detail beyond the schema, so this is the baseline score for a well-covered single parameter.

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

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

The description states a specific verb and resource: fetching one supplier by id. It also distinguishes this from the sibling list/create supplier tools by making clear this returns a single supplier and enumerates the included fields.

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 saying 'one supplier by id,' but it does not explicitly say when to use this versus precoro_list_suppliers or how to obtain the id. There are no exclusions or alternatives named.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them by enumerating the fields returned (file name, supplier, gross total, currency, status, dates), which compensates for the absence of an output schema, but says nothing about ordering, totals/counts, or how 'status' values behave.

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

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

A single front-loaded sentence that defines the resource, lists the returned fields, and ends with the endpoint path. No filler; the trailing GET path is slightly redundant with the tool name but harmless.

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

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

For a 2-parameter read-only list with no output schema, the returned-field list is the key contribution and it is present. Missing are sibling routing (inbox vs posted invoices), any note on pagination/volume, and status semantics, which an agent would need to use the result set sensibly.

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

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

Schema coverage is 100% and both parameters carry full descriptions including defaults, page-size enums and the next_page convention. The description adds no parameter-level information, 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 accounts-payable inbox documents) and defines the resource as OCR-read uploaded/emailed supplier invoices, which separates it from the generic invoice list. It never names precoro_list_invoices or precoro_get_invoice, so the boundary with those siblings is left to inference.

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

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

The parenthetical implies this is the entry point for documents awaiting processing, but there is no explicit statement of when to choose this over precoro_list_invoices, nor when to then call precoro_get_invoice or precoro_approve_document. Usage is implied rather than directed.

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 value by spelling out which budget fields come back, but it says nothing about pagination limits, default ordering, what happens when there are zero budgets, or whether the 'used' amounts are computed live.

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 front-loads the resource and enumerates returned fields with no filler, followed by the endpoint for traceability. Slightly list-heavy phrasing but every clause 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?

There is no output schema, so the field enumeration is the main way an agent learns what a budget record contains, and the description delivers it. Pagination is fully covered by the schema, so the only real gap is ordering/empty-result behavior for a simple two-param read tool.

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

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

Schema description coverage is 100% and both params (page, per_page) are documented with defaults, allowed per_page values and the next_page chaining convention. The description adds nothing beyond the schema, 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?

Starts with a specific verb (List) plus resource (budgets) and then enumerates the fields returned: name, period, total sum, consumption across requisitions/orders/invoices/expenses, and limit enforcement. The resource is distinct from every sibling list tool, so an agent can route correctly without an explicit exclusion clause.

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: the tool lists budgets, so an agent infers it is the entry point for budget discovery. There is no statement about when to prefer it over list_reference_data or other list endpoints, and no prerequisites or filters are mentioned (the tool has no filter params at all, which is itself worth stating).

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 endpoint path GET /contracts and the returned field set, but says nothing about page sizes, rate limits or result ordering.

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

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

A single tight sentence that front-loads the resource and then lists the payload fields; every clause carries information and nothing is wasted.

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 enumerated return fields do useful work, and annotations cover the safety profile. The only gap is pagination semantics, which are relegated to the schema rather than the description.

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

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

Schema description coverage is 100%, so page and per_page are fully documented in the schema itself. The description adds no parameter semantics 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?

States a specific verb (List) and resource (supplier contracts) and enumerates the fields returned: number, supplier, dates, auto-prolong. This clearly separates it from the many list_* siblings (suppliers, items, invoices) without naming them 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?

No guidance on when to use this versus precoro_get_supplier or precoro_list_suppliers, and no mention of pagination behavior or prerequisites. The agent is left to infer usage entirely 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by naming the underlying GET endpoint and summarizing the returned fields and filter behavior, though it does not discuss pagination or rate limits.

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

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

Two sentences, front-loaded with purpose and scope, followed by the available filters and endpoint. Every clause carries useful information and there is no repetition or 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 read-only list tool with full schema descriptions and annotations, the description is complete: it defines expense documents, lists key returned fields, identifies filter dimensions, and cites the endpoint. No output schema exists, but the description still gives enough return-value context for an agent to 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 description coverage is 100%, and every parameter is already well documented in the schema. The description restates the filter categories but does not add syntax, constraints, or examples beyond what the schema 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 expense documents") and immediately scopes what an expense is: "purchases without a purchase order." It also names the returned fields and the endpoint, making it clearly distinguishable from sibling list tools such as list_invoices or list_purchase_orders.

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

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

The description gives explicit filtering contexts: status, last-modified time, approval date range, and "waiting for my approval." It does not explicitly say when not to use this tool or name an alternative list tool, but the scope definition strongly implies the right usage context.

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 backing endpoint (GET /invoices) but nothing about pagination behavior, result limits, or permissions; it also never notes that 'waiting_for_my_approval' scopes to the API key's owner, which is only 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?

One sentence of content plus the endpoint, front-loaded with the resource and the field list, with zero filler. Nothing is repeated and no sentence could be removed 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 list tool with no output schema, full schema coverage and strong annotations, the description covers purpose and filter surface adequately. What is missing (pagination contract, default sort, result shape) is minor given the schema already documents paging via next_page.

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 explains every parameter in detail (status code meanings, kind codes, date formats, next_page usage). The description only restates the filter categories at a high level, adding no syntax or 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?

The description gives a specific verb ('List') and resource ('supplier invoices and credit notes') and even enumerates the returned fields (supplier, totals, currency, dates, paid sum, approval/payment status), which makes it clearly distinct from precoro_get_invoice and precoro_list_expenses. It stops short of naming a sibling explicitly, so it is clear but not fully differentiated.

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 lists the available filter dimensions (status, kind, last-modified, approval date range, waiting-for-my-approval), which implies when the tool is useful, but it never states when to prefer it over precoro_list_ap_inbox or precoro_get_invoice for a single record. Usage is inferable rather than 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 underlying endpoint (GET /items) and the field set, but says nothing about pagination behavior, result ordering, or volume beyond what the schema 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?

Three short, front-loaded sentences with no filler; the resource and returned fields come first, then the filter, then the endpoint. Minor redundancy with the title ('List catalog items') but otherwise tight.

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 enumerates the returned fields (name, SKU, unit, price, currency, supplier, group, custom fields), which an agent needs. All three parameters are documented in the schema, so the definition is essentially complete, lacking only guidance on result volume or ordering.

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, per_page and modified_since are already well documented in the schema, including the next_page chaining hint. The description's only parameter-level contribution is restating the modified-since filter, 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 catalog items (products and services)') and enumerates the returned fields, so an agent knows exactly what it gets back. It does not explicitly contrast with the single-record sibling precoro_get_item, which would be needed for 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?

Mentions one usage lever ('Filter by last-modified time') but gives no explicit when-to-use guidance or alternates such as precoro_get_item for a single item. Usage is implied by the verb 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 destructiveHint=false, so safety is covered. The description adds useful behavioral context by defining the returned fields, including what status and kind codes mean, which is valuable since there is no output schema. It does not discuss pagination behavior beyond what the schema says, but that is a minor omission.

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

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

The description is a single compact sentence with the core scope front-loaded, followed by the endpoint. Every element earns its place and there is no redundant filler.

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

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

With no output schema, the description appropriately names the key fields returned: pay date, sum paid, status, kind, and linked invoice or expense. Pagination is handled by the schema. It is complete enough for a listing tool, though it could mention any default filtering or sorting behavior.

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

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

Schema description coverage is 100% and both parameters (page, per_page) are fully documented in the schema. The description adds no parameter-specific meaning beyond this, so 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?

The description states a specific verb and resource ('List payments recorded against invoices and expenses') and names the data it returns, so it is clearly distinguishable from singular get_* siblings. It does not explicitly contrast itself with list_invoices or list_expenses, 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?

Usage is implied by the word 'List' and by the scope 'recorded against invoices and expenses', but the description gives no explicit when-to-use guidance, exclusions, or alternative tools for narrowing results. An agent can infer it is the payments listing endpoint, but nothing more is 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 readOnly/openWorld/no-destructive, so safety is covered. The description adds genuinely useful behavior: pagination via next_page, the field set returned, and inline meaning of receiving/payment status codes that the agent would otherwise have to infer.

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 the resource and returned fields, then adds filtering and pagination in efficient follow-up clauses. The dense status-code enumeration is long but load-bearing; only minor trimming would help.

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 carries the return-value burden by listing the fields returned and clarifying that line items are excluded. Filters and pagination are covered, leaving the agent able to 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 description coverage is 100%, so the schema already documents all 8 parameters including their value ranges. The description restates the filter axes (status, modified time, approval range, waiting for my approval) without adding format details 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 (List) and resource (purchase orders), then enumerates exactly what each row contains (number, supplier, totals, statuses). It distinguishes itself from the sibling get_purchase_order by noting line items come only from that 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?

Explicitly routes the agent to precoro_get_purchase_order for line-item detail and lists the available filter axes and pagination approach. Lacks an explicit 'when not to use' exclusion beyond the line-item note, keeping it short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds genuinely new context: that results are header-level only and omit line items, plus the underlying endpoint. It does not discuss rate limits or result ordering, so it is not complete, but it is well beyond what the annotations supply.

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 what the tool returns and immediately followed by the sibling routing rule and filter surface. No repeated schema content, 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?

No output schema exists, so the description carries the burden of describing return values, which it does by enumerating the fields returned per requisition. Pagination is handled in the schema; the only minor gap is that result ordering and default sort are 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 coverage is 100%, so the schema already documents all seven parameters including status code meanings and pagination semantics. The description only echoes the filter categories (status, last-modified, approval date range, waiting-for-my-approval) without adding syntax or selection advice, so 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?

Specific verb + resource ('List purchase requisitions') with an explicit field enumeration (requester, location, totals, required date, approval status) that tells the agent what a row contains. It also explicitly partitions the domain from precoro_get_purchase_requisition by stating line items come only from that 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?

Clearly frames this as the browse/filter entry point by listing the four filter dimensions, and names the sibling to use when line-item detail is needed. It stops short of full when-not guidance (e.g., choosing this over precoro_list_purchase_orders or precoro_list_ap_inbox).

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

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

Annotations already declare this as a read-only, non-destructive, open-world list operation. The description adds useful context beyond them: the underlying endpoint (GET /receipts), the summary fields returned, and the fact that line items are not included here. Pagination and auth behavior are left to the schema/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?

It is three efficient sentences, front-loaded with what the tool returns and immediately followed by the sibling routing note and filter options. Every sentence carries useful information.

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

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

For a read-only list tool with full schema coverage and annotations, the description covers the main points: what is listed, which fields are included, and where detailed line items must be fetched. Minor omissions like default ordering or pagination behavior are already handled by 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 description coverage is 100%, so the schema already documents pagination, status codes, and date formats in detail. The description only summarizes available filters without adding syntax or format information, so it meets the baseline without adding 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?

The description states a specific verb and resource ('List goods receipts') and clarifies scope ('what was delivered against purchase orders'), listing the fields returned. It explicitly distinguishes itself from precoro_get_receipt, which is where line items and quantities come from.

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

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

It tells the agent what can be filtered (status, last-modified time, approval date range, waiting for my approval) and explicitly routes detail retrieval to precoro_get_receipt. It does not explicitly contrast against other list tools such as precoro_list_purchase_orders, but the purpose and the sibling callout are clear enough.

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 destructiveHint=false, so safety is covered; the description adds genuinely new behavioral facts: bank details are never returned (a data-exclusion rule) and each table's field inventory. It omits response shape and pagination behavior beyond the schema's next_page hint.

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 purpose and the downstream-id use case are front-loaded, and the field inventories are compact. The trailing list of GET endpoint paths largely restates the enum values and is the one segment that does not earn its place.

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

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

With no output schema, the description still tells the agent what each table yields and what is deliberately excluded, which is the critical missing piece. Only the pagination/return envelope is undocumented, and the schema's next_page hint partly compensates.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra credit by explaining what each enum value contains (users carry name/email/roles; document_custom_fields covers departments, projects, classes, GL accounts), which meaningfully helps the agent pick the right table. Page/per_page 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 (List) and resource (configuration/reference table) and then enumerates the exact table set, with parenthetical contents for the non-obvious ones. This clearly separates it from sibling list tools such as precoro_list_items or precoro_list_suppliers, which return transactional records rather than configuration data.

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 it to find the ids that purchase requisitions and suppliers need (location, legal entity, custom field)" gives a concrete trigger tied to downstream create calls. It does not name sibling tools as alternatives or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: an explicit field-level guarantee ('Bank details are never returned') and the availability of a last-modified filter, which matters for sync-style workflows. It stops short of describing pagination or ordering behavior.

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

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

Two compact sentences: the first front-loads the action and enumerates return fields, the second carries the filter note and endpoint. Every clause is informative, though the long comma-separated field list reads densely rather than being structured.

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

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

There is no output schema, so the description must convey what comes back — and it lists the returned fields explicitly while noting the excluded bank details. Combined with a fully documented input schema for pagination, an agent has enough to invoke this correctly; only ordering and total-count behavior are 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%, and the schema documents page, per_page, and modified_since thoroughly (including the 'pass the previous reply's next_page' instruction). The description only restates the modified_since filter in general terms, adding no syntax or semantics 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?

The description opens with 'List suppliers' — a specific verb and resource — then enumerates the returned fields (name, code, currencies, payment conditions, minimum order sum, contacts, addresses, accounting ids, status) and the endpoint. It is clearly distinguishable from the sibling read of a single supplier (precoro_get_supplier) and from precoro_create_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?

'Filter by last-modified time' indicates one supported use case, and the 'List' verb implies bulk retrieval versus the single-record get_supplier sibling. However, there is no explicit statement of when to prefer this tool over precoro_get_supplier or precoro_list_reference_data, and no stated 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 destructiveHint=true and non-idempotent, so the safety profile is covered; the description adds real value by disclosing that a comment is mandatory and that the creator is notified and will see it — a side effect not captured anywhere in structured fields. It does not mention required permissions or whether rejection is reversible.

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: the WRITE prefix and verb lead, the precondition and required side effect follow, and the endpoint is last. 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 3-parameter mutation with no output schema and rich annotations, the description covers trigger state, required input, side effects, and endpoint. It leaves out only permission requirements and response behavior, which are minor given no output schema exists.

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

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

Schema coverage is 100% with descriptions on all three parameters, including the IDN-vs-internal-id distinction and the 800-char comment limit. The description only restates that the comment is required, adding nothing 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 (reject/deny) and resource (document) plus the precondition that it must be waiting for the key user's approval, which separates it from the get_*/list_* siblings. It does not explicitly name precoro_approve_document as the counterpart, so it stops just short of full sibling differentiation.

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 'waiting for the key user's approval' gives a clear condition for use and implicitly excludes documents in other states. No explicit when-not guidance or permission prerequisites are given, but the trigger context is unambiguous.

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, destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the document moves into the approval flow, may be auto-approved if no approval is needed, and approvers are notified as a side effect. It stops short of saying whether the submission can be withdrawn or re-submitted after a rejection.

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 segments with the 'WRITE:' prefix and the effect front-loaded, followed by the notification side effect and the endpoint. Nothing is repeated and nothing is wasted.

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 mutation with no output schema, the description covers the trigger condition, the resulting state transition, the auto-approval branch, and the notification side effect, which is enough to call it correctly. It omits error behavior for a non-open document, which is the only meaningful gap.

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

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

Schema description coverage is 100%, and the enum on 'document' plus the note that 'idn' is the company's own document number are fully documented in the schema. The description only echoes the parameters via the POST path template, adding no format or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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

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

Opens with a specific verb ('confirm') and resource ('a draft (open) document') and states the resulting state change: it enters the approval flow. It implicitly distinguishes itself from precoro_approve_document by describing submission rather than approval, but 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 parenthetical '(open)' establishes the precondition that the document must be a draft, which is real usage guidance. However, there is no explicit when-not guidance and no routing to precoro_approve_document or precoro_reject_document, so the agent must infer which sibling to pick.

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