Billomat MCP by usefulapi

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing a server-side validation rule (status must be DRAFT) and clarifying it does not finalize/send the document. It stops short of covering idempotency behavior, which is notable given idempotentHint=false — repeated calls presumably append duplicate items, and that is not stated.

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 an uppercase WRITE marker and the core constraint. Every clause carries routing or behavioral information; 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 12-parameter mutation tool the description plus a fully documented schema is nearly sufficient, and the draft-only constraint is the key missing piece it supplies. With no output schema, however, it never says what comes back (e.g. the created item id), which would help an agent chain subsequent calls.

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

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

Schema description coverage is 100%, so all 12 parameters — including the article_id fallback semantics for title/quantity/unit_price — are already documented in the schema. The description adds no parameter-level meaning beyond it, which is the expected baseline when the schema carries the load.

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 ('add one line item to an invoice') and immediately scopes it to draft invoices only. An agent can distinguish this from billomat_list_invoice_items or billomat_create_draft_invoice without opening any 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?

It gives an explicit precondition ('an invoice that is still a DRAFT') and an explicit when-not ('Billomat refuses it for any other status'), plus a negative scope ('Does not complete or send the invoice'). Nothing about when to call it is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=true, so the safety profile is covered. The description usefully adds that Billomat assigns the article number, which matters because there is no output schema. It does not, however, warn that repeated calls create duplicates (relevant given idempotentHint=false).

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

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

Two tight sentences with the operation mode front-loaded and zero filler. Every clause carries information: mutation type, resource, domain, and the server-side numbering behavior.

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 an eight-parameter write tool with no output schema, the description covers the essential purpose and the key return fact (assigned article number), and the schema covers the rest. It omits behavioral caveats that matter here, such as duplicate creation and net-vs-gross price handling, leaving it adequate but not fully self-sufficient.

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

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

Schema description coverage is 100%, so all eight parameters are already documented in the schema. The description only echoes 'product or service' and 'with a price', adding no syntax, format, or defaulting detail beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb and resource ('create a new article'), clarifies the domain distinction (product or service), and notes the server-assigned article number. It does not explicitly distinguish itself from siblings like billomat_get_article or billomat_list_articles, but the write intent is unmistakable.

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 'WRITE:' prefix signals a mutation but gives no when-to-use guidance, no prerequisites (e.g., that tax_id/unit_id should come from the list tools), and no mention of what to do if the article already exists. Nothing routes the agent between this and alternative tools.

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

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

Annotations already declare the write, non-idempotent, side-effecting profile, so the bar is lower. The description still adds real context beyond them: Billomat assigns the client number (so the agent should not supply one) and nothing is dispatched to the customer. It omits what the call returns and any failure modes, which keeps 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?

Four short sentences, none wasted, with the operation type front-loaded. Each sentence carries a distinct fact: operation, number assignment, no external notification, duplicate check.

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 an 18-parameter write tool with no output schema and no required fields, the description covers the operation, the side-effect boundary, and the duplicate risk. It does not tell the agent what the response contains or which fields are practically required for a usable client record, leaving a small 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% across all 18 parameters, so the schema fully carries parameter meaning. The description adds no field-level detail (e.g. which fields matter for an individual vs. company client) beyond what the schema already states, so the baseline of 3 applies.

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

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

States a specific verb and resource ('create a new client (customer) in Billomat') and leads with 'WRITE:', which immediately separates it from the many billomat_get_* and billomat_list_* siblings. An agent can distinguish it from billomat_update_client and billomat_create_article without opening any schema.

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

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

Gives an explicit precondition naming a sibling tool: 'Check billomat_list_clients first to avoid duplicates.' That is actionable routing guidance. It stops short of 5 because it never states when not to use this tool or how it relates to billomat_update_client for existing records.

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 write/non-idempotent/destructive; the description adds substantive behavior the annotations do not convey: the document has no number yet, is not sent, is not finalized, and nothing is charged. It omits duplicate-creation/idempotency guidance, which matters given idempotentHint=false.

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 WRITE marker, then the outcome-critical constraints in two tight sentences. Every clause earns its place; nothing is repeated from the schema or annotations.

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

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

For an 11-parameter create tool with full schema coverage and no output schema, the description sufficiently frames the result (draft, unsent, unnumbered) so the agent understands the object it produced. It does not mention what identifier comes back for later add_invoice_item calls, a minor gap.

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

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

Schema description coverage is 100%, so every parameter including nested item fields is already documented with defaults, constraints and cross-references (article_id usage). The description only adds that line items are optional and that more can be added later, 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?

States a specific verb and resource (create an invoice as a DRAFT) with the exact scope: for a client, optional line items. It clearly separates this from the other create siblings (create_draft_offer, create_client, create_article) and from the read siblings (get_invoice, list_invoices) in one sentence.

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

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

Gives clear workflow context: the result is unfinished, so the agent should review and complete it in Billomat rather than treat it as final, and line items can be added later. It does not explicitly name the alternative for post-creation edits (billomat_add_invoice_item) or state when-not-to-use, so it stops short of a full routing statement.

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

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

Annotations already declare readOnlyHint=false / idempotentHint=false / destructiveHint=true, so the write nature is covered. The description adds real value on top: the result is a draft with no number, it is not sent, and completion happens later in Billomat — useful lifecycle context for an agent deciding whether this call alone finishes the job.

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

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

Two tight sentences with the 'WRITE:' marker and the draft-state constraint front-loaded. No filler, though it is slightly dense in the second sentence.

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 an 11-parameter creation tool with only one required field, full schema coverage, and no output schema, the description covers purpose and outcome adequately. Minor gaps: no mention of auth/permission needs or what the response returns, but these are not strictly required here.

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

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

Schema description coverage is 100%, so every one of the 11 parameters (client_id, items, net_gross, validity_days, etc.) is already documented in the schema. The description only adds 'with optional line items', which is already implied, so the schema does the heavy lifting — 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 ('create an offer (Angebot) as a DRAFT') plus the optional line-item scope, so it is clearly distinguishable from list_offers/get_offer and from create_draft_invoice. It stops short of naming a sibling explicitly, but the resource and draft state are 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?

Provides clear context for when this is appropriate: it produces an incomplete, unnumbered, unsent draft that should be reviewed and completed in Billomat. It does not name an alternative or spell out when NOT to use it, so it falls just short of explicit routing guidance.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is disclosing what the record contains (prices, unit, tax, supplier). It says nothing about permissions, error behavior for missing IDs, or expansion options—acceptable but not rich given the low bar set by 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?

A single front-loaded sentence with no filler; the resource and its payload are stated immediately with zero redundancy.

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

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

For a simple one-parameter read with no output schema, the description covers what is retrieved, which is the main missing piece an agent would otherwise lack. Nothing critical about calling the tool correctly is 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?

Only one parameter and schema description coverage is 100%, so the schema fully documents that the id comes from billomat_list_articles. The description adds no additional parameter meaning, which is the expected baseline when the schema does the 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 and resource ('Get one article') and enumerates the notable contents (prices, unit, tax, supplier), which distinguishes it from billomat_list_articles and billomat_create_article. It stops short of naming those siblings explicitly, so it is clear but not maximally 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?

The word 'one' implies single-record retrieval by ID versus the list tool, and the id parameter description points back to billomat_list_articles, but the description itself gives no explicit when-to-use or alternative-selection guidance. Usage is only inferable.

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

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

readOnlyHint=true already establishes this is a safe read, so the description only needs to add context. It partially does so by disclosing that a broad set of fields (bank details, revenue, payment terms) is returned, which helps the agent anticipate payload size, but it says nothing about not-found behavior or permission 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?

A single front-loaded sentence with zero filler; every phrase contributes either the verb, the resource, or the returned content.

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 does well by enumerating the returned fields, which substitutes for a return-value spec. It stops short of noting error/nonexistent-id handling, but nothing essential for 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%; the id parameter is fully documented in the schema, including its provenance from billomat_list_clients. The description adds no further parameter meaning, 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+resource ('Get one client') with the returned fields enumerated (address, contact person, bank details, payment terms, revenue). The word 'one' distinguishes it from billomat_list_clients, but no sibling is named explicitly.

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

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

Usage is implied by 'Get one client' plus the schema note that the id comes from billomat_list_clients, but the description never states when to retrieve a single client versus calling billomat_list_clients or billomat_update_client. No exclusions or alternatives 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?

readOnlyHint=true already declares this as a safe read, so the description's job is lighter. It adds content-level detail (the fields returned: name, address, bank details, tax numbers, currency), which is genuinely useful, but discloses nothing about permissions, scoping to the authenticated account, or response shape.

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

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

A single sentence with the resource front-loaded and no filler. 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?

With no output schema and no parameters, the description carries the burden of telling the agent what comes back, and the field enumeration does that adequately for a simple account-metadata read. It stops short of only marginally useful details like currency-format semantics or scope of 'own'.

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?

Zero parameters, so the baseline is 4. The description still earns its keep by naming the data categories the tool surfaces, which is the closest thing to a return-value contract in the absence of an output 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: shows the account's own company data. The parenthetical enumeration of fields makes the scope concrete. It is distinguishable from siblings like billomat_get_client or billomat_get_current_user, though it doesn't explicitly say so.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives. For a singleton read tool the omissions are mild, but the description gives no routing help against get_current_user or get_client.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered, and the description does not contradict them. It adds nothing beyond that, however: no note on what a not-found id returns, error behavior, or the shape of the single record, which is the kind of context that would earn a higher score.

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 short sentence with zero waste, and the verb plus resource is front-loaded. It is efficient, though the brevity edges toward under-specification rather than tight completeness.

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

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

For a one-parameter, read-only lookup with 100% schema coverage and annotations covering safety, the minimal description is close to sufficient. It still omits any usage context (when to fetch a confirmation directly) and return-value expectations, since 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% and the id parameter is fully documented in the schema itself, including its source (billomat_list_confirmations). The description adds no syntax, format, or filtering detail beyond what the schema 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?

The description names a specific verb and resource ("Get one order confirmation"), and "one" hints at single-record retrieval versus a list. It does not, however, distinguish this tool from the many sibling get_* tools or from billomat_list_confirmations beyond that single word, leaving scope 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?

There is no explicit when-to-use guidance or named alternative. The only routing hint (the id comes from billomat_list_confirmations) lives in the schema, not the description, so an agent gets no stated condition for choosing this over list_confirmations or other get_* siblings.

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 a matching title, so the safety profile is covered for free. The description adds nothing beyond that: no note on error behavior for missing ids, permissions required, or what a returned credit note contains. A getter this terse leaves the description earning almost no incremental credit.

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 words, front-loaded with the verb and resource, with zero filler. It is appropriately sized for a one-parameter getter, though it is arguably under-specified rather than genuinely optimized.

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-id read tool with full schema coverage and a readOnlyHint annotation, the minimum needed to call it correctly is present. There is no output schema, so nothing describes the return shape, and neither the id source nor error cases are covered in 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%, and the schema itself documents the id and even points to billomat_list_credit_notes as the source. The description contributes no additional parameter meaning, 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 (Get) and resource (credit note) with a singular scope ('one') that implicitly distinguishes it from the sibling billomat_list_credit_notes. It never names or contrasts with any sibling explicitly, so it lands just short of 5.

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

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

There is no when-to-use guidance, no mention of the required id coming from a list call, and no stated alternative to this tool. Usage is only inferable from the name and the 'one' scope.

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 readOnlyHint=true already declaring it a safe read, the description adds the concrete payload (name, email, role, rights), which is meaningful because no output schema exists. It doesn't mention auth prerequisites or failure modes, but it adds real context beyond the annotations.

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

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

Two sentences, zero waste, and the identity of the returned resource is front-loaded before the usage hint. Each sentence earns its place.

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

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

For a zero-parameter read tool with annotations covering safety and no output schema, the description supplies exactly what's needed: what the tool returns and why to call it. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool is 4. No parameter semantics are needed or missing.

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: returns the Billomat user the API key belongs to, and enumerates the returned fields (name, email, role, rights). This clearly distinguishes it from the many sibling get_* tools that fetch clients, articles, invoices, or companies rather than the authenticated user.

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?

Adds an explicit use case: 'Use it to check which rights the key has.' This tells the agent when to reach for it, though it names no alternative or exclusion conditions, so it stops short of full 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?

The readOnlyHint annotation already establishes this is a safe read, and the description adds nothing on top of it: no behavior for a missing/invalid id, no note on what fields are returned, no scoping or permission notes. It neither enriches nor contradicts the annotation.

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

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

A single four-word sentence with no wasted tokens and the essential verb+resource up front. It is terse rather than padded, though it borders on under-specification.

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 and a readOnlyHint annotation, the definition is functionally sufficient to invoke it, but it omits any return-shape or error-behavior context that would help an agent interpret the result.

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

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

Schema description coverage is 100% and the id parameter is fully documented in the schema, including its origin ('from billomat_list_delivery_notes'). The description adds no parameter meaning, 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 one delivery note'), which clearly distinguishes it from the sibling billomat_list_delivery_notes. It stops short of naming alternatives explicitly, but the singular 'one' carries the 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?

There is no guidance on when to use this versus billomat_list_delivery_notes, nor any mention of prerequisites such as needing an id obtained from the list tool. The usage context is only implied by the 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 the safety profile is covered. The description adds only that amounts and the open amount are included, which is modest extra context; it says nothing about permissions, error behavior, or response structure.

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 with the key information front-loaded; no filler or redundancy. It is short almost to the point of under-specification, 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 read-only single-record fetch with annotations covering safety and 100% schema coverage on the lone parameter, the minimum is met. However, with no output schema, the description could do more to characterize the returned invoice fields beyond 'amounts and open amount'.

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?

One parameter with 100% schema description coverage, and the schema already explains the id and its source. The description contributes no additional parameter semantics, 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?

Specific verb+resource: 'Get one incoming invoice' clearly separates it from the list/other entity getters among siblings. It also hints at the payload ('amounts and open amount'). It does not explicitly name the sibling list tool, 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?

No when-to-use guidance, no prerequisites, and no alternatives mentioned in the description. The only routing hint (ids come from billomat_list_incoming_invoices) lives in the schema, not the description.

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 covers the safety profile, so the description's added value is disclosing what is returned (status, totals, dates, client, payment terms) and, importantly, what is NOT returned (line items, which live in a sibling tool). It does not mention failure modes (e.g., unknown id), so it stops short of full behavioral disclosure.

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

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

Two short sentences, no filler, with the core purpose front-loaded and the line-item caveat placed immediately after so the reader learns the boundary before invoking.

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 correctly takes on the job of describing the return payload and the payload's boundary (no line items), and it points to the tool that supplies them. For a one-parameter read tool this leaves nothing an agent needs missing.

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

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

Schema description coverage is 100% and the schema already explains that the id comes from billomat_list_invoices, so the structured field carries the full burden. The description adds no syntax or format detail for the id beyond that, which is the expected baseline when the schema 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+resource ('Get one invoice'), enumerates the returned fields (status, totals, dates, client, payment terms), and distinguishes itself from the list tool by scoping to 'one'. It even routes the related concern (line items) to the correct sibling, so an agent can separate it from billomat_list_invoices and billomat_list_invoice_items 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?

The single-record framing plus the explicit pointer that line items come from billomat_list_invoice_items clearly signals when this tool applies versus the list/items tools. However, it never explicitly names billomat_list_invoices as the way to obtain the id (that hint only lives in the schema), so usage guidance is strong but not fully self-contained.

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 structurally. The description adds modest value by naming the fields returned (status, totals, validity, client), which is useful since no output schema exists, but it says nothing about error cases or whether a missing id fails.

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 compact sentence with the resource and returned fields front-loaded; no filler, no redundancy. Every clause earns its place.

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

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

For a read-only, single-parameter tool with annotations covering safety, the definition is nearly sufficient, and the field list partly compensates for the absent output schema. It would be complete with a pointer to the sibling list tool for obtaining the 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?

Only one parameter and schema description coverage is 100%, so the schema already documents the id fully, including its provenance ('from billomat_list_offers'). The description adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb (get) and resource (one offer), and the parenthetical enumerates the payload (status, totals, validity, client). The singular 'one offer' implicitly contrasts with the sibling billomat_list_offers, though it never names it.

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

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

Usage is only implied: fetch a single offer rather than enumerate them. There is no explicit statement of when to prefer this over billomat_list_offers, nor any prerequisite such as where the id comes from (that hint lives in the schema, not the description).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds nothing beyond that - no note about what is returned, whether a missing id errors, or any auth/rate considerations - so it contributes no behavioral context of its own.

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 with zero padding or redundancy. It is efficient, though the terseness borders on under-specification rather than tightness.

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 definition is minimally adequate since the schema carries the parameter. However, the absence of any return-value or sibling-routing detail leaves an agent to infer the rest.

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 single id parameter is fully documented in the schema (including its origin in billomat_list_reminders). The description adds no parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb (get) and resource (payment reminder), and 'one' implies single-record retrieval as opposed to the list variant. It does not explicitly name or differentiate itself from billomat_list_reminders, 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 offers no guidance on when to use this tool versus billomat_list_reminders or any other sibling. The only routing hint ('from billomat_list_reminders') lives in the schema, not the description, so the description itself gives no 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, so the safety profile is covered. The description adds genuine behavioral value in the absence of an output schema by disclosing what the response contains: address and bank details. It does not cover failure behavior (e.g., missing id), 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?

One sentence, front-loaded with the verb and resource, with the return payload summarized at the end. No filler or redundant restatement of the tool name.

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

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

For a simple single-record read with full schema coverage, readOnlyHint, and no output schema, the description supplies the one thing structured data doesn't: what fields come back. Only error/empty-result behavior is left unaddressed, a minor gap.

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

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

Schema description coverage is 100% and the single 'id' parameter is fully documented in the schema, including its source (billomat_list_suppliers). The description adds nothing about the parameter, 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 ('Get') and resource ('supplier') with added scope ('with address and bank details'), so the agent knows exactly what entity is fetched. It does not explicitly distinguish itself from the sibling billomat_list_suppliers, but 'one supplier' implies single-record retrieval.

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

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

No when-to-use guidance, no mention of the alternative (billomat_list_suppliers) for enumerating suppliers, and no prerequisites. The single-record framing hints at usage, but nothing steers the agent between this and the list tool.

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

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

Annotations already declare readOnlyHint=true, and the description merely repeats 'Read-only' rather than adding new behavioral information. It does not describe what the aggregated response contains or how multi-dimension grouping nests results, which matters given there is no output schema.

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

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

Three short statements with no filler; the core capability is front-loaded, followed by the filter delegation and the safety note in descending order of importance.

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

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

Given 13 parameters, no output schema, and a sibling that shares the filter set, delegating filters to billomat_list_invoices is an efficient and complete strategy. The one remaining gap is that the return shape of a grouped-totals response is never hinted at, which is meaningful without an output schema.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters including group_by's pattern and ordering rule. The description's example (group_by=client,year) reinforces but does not add meaning beyond the schema, 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 operation (aggregate invoice totals) with the exact grouping dimensions available, plus a worked example. It is clearly distinguishable from billomat_list_invoices, which returns individual invoices rather than grouped totals.

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?

Points the agent at billomat_list_invoices for filter semantics ('takes the same filters'), which is useful routing context, and signals read-only usage. It does not state an explicit when-to-use/when-not rule (e.g. use this instead of listing invoices when you only need aggregates), so it stops short of a 5.

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

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

readOnlyHint=true and the title already establish this as a safe read, so the burden is lower. The description adds one real behavioral fact — results are paged — but says nothing about default page size behavior, rate limits, or the shape of a page of results beyond the parenthetical field list.

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, no filler, with the core resource and return content front-loaded before the pagination note. Nothing here is redundant with the name alone.

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

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

For a read-only listing tool with 10 optional filters and no output schema, telling the agent what the rows contain (prices, units, tax) and that paging exists is close to sufficient. Minor gaps remain around result ordering defaults and page-size defaults, though those are covered in schema parameter descriptions.

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 every one of the 10 filters is already documented in the schema (page/next_page, tags as Schlagworte, unit_id sourced from billomat_list_units, order_by syntax). The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb ('List') and resource ('articles'), and usefully disambiguates that articles include both products and services, plus what fields come back (prices, units, tax). It does not explicitly contrast itself with siblings like billomat_get_article or billomat_create_article, but the list-vs-get-vs-create distinction is unambiguous from the name.

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

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

'Paged' plus the schema's 'Use next_page from the previous reply' implies the pagination workflow, and 'List' makes the bulk-retrieval use case self-evident. However, there is no explicit when-to-use guidance, no exclusion of the single-record sibling (billomat_get_article), and no mention of when to prefer this over a filtered lookup.

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

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

Annotations already declare readOnlyHint=true and a 'List or search clients' title, so safety is covered. The description adds useful behavioral context with 'Paged', but discloses nothing about result limits, ordering defaults, or what the response 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 sentences, front-loaded with the operation and resource, then the filter dimensions, then the paging note. No redundant or filler 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 12-parameter read-only list tool with no required params and full schema coverage, the description covers purpose, filters, and pagination. It leaves return-shape and result-cap details unstated, but the absence of an output schema makes this a minor gap.

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

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

Schema description coverage is 100%, so every parameter (name, note, page, tags, email, order_by, first/last_name, invoice_id, country_code, client_number, per_page) is already documented in the schema. The description only summarizes these filters and adds no format or syntax detail beyond it, 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 ('clients/customers') and enumerates the filterable dimensions, so the agent knows it is a filtered-listing tool. Sibling differentiation (vs billomat_get_client or billomat_create_client) is implied by 'List' rather than stated explicitly.

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

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

The filter list implies the search/retrieval context, but there is no explicit when-to-use guidance, no mention of when to prefer billomat_get_client (single client) over this list, and no stated prerequisites. Usage is inferable 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, so the safety profile is covered. The description adds "Paged", a genuine behavioral trait, but the schema already documents page/per_page and next_page semantics, so the added value is thin. Nothing about result size caps, ordering defaults (beyond schema) or empty-result behavior is disclosed.

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

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

Two tight sentences: the first front-loads the resource, the filter dimensions and the enum values, the second tacks on pagination in a single word. No filler or restatement of the title.

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

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

For a read-only, 14-optional-parameter list tool with full schema coverage and a pagination-safe readOnly hint, the description covers purpose, filters and paging adequately. The only mild gap is that with no output schema, nothing is said about the shape of returned confirmations (id/number fields needed for follow-up calls), though that is a minor omission for a list endpoint.

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 per-parameter descriptions and formats, so the baseline is 3. The description's summary of filter dimensions (client, status, number, date range, text) mirrors what the schema already states and adds no syntax, default, or combination rules beyond it.

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

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

Names a specific verb and resource ("List order confirmations") and even supplies the German domain synonym (Auftragsbestaetigungen), which helps disambiguate in a German accounting toolset. It is clearly separable from the singular sibling billomat_get_confirmation and from billomat_list_offers/invoices by the resource noun.

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 filter enumeration (client, status, number, date range, text) implies the contexts in which this tool is appropriate, but there is no explicit when-to-use statement, no guidance on when to prefer billomat_list_offers or billomat_get_confirmation instead, and no note that all filters are optional.

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's only behavioral addition ('Paged') is fully covered by the page/per_page schema fields. It discloses nothing about auth, rate limits, result ordering defaults, or what a page 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 tightly worded sentences with the core purpose front-loaded and no filler. The status enum values and the 'Gutschriften' gloss mildly duplicate structured data, keeping it just short of ideal.

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 14 fully documented parameters and readOnlyHint covering safety, the schema carries most of the load, but there is no output schema and the description says nothing about what a page of credit notes contains or how paging terminates. It is adequate but leaves the return shape entirely unspecified.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters, including date formats, status pattern and pagination. The description's summary of filterable dimensions (client, status, date range, text) adds 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?

Clear verb (List) plus specific resource (credit notes) with the German term 'Gutschriften' for disambiguation, and it enumerates the filter dimensions. It is distinguishable from the many list_* siblings by resource name, though it does not explicitly contrast with billomat_list_invoices or billomat_get_credit_note.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative (e.g. use billomat_get_credit_note for a single record). The filter list hints at capabilities but not at selection between sibling tools.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds that results are 'Paged', which is genuine operational context beyond the annotations, but says nothing about page size defaults, total counts, or empty-result behavior (the schema carries next_page 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?

Two sentences, no filler. The filter list and paging fact are front-loaded, so an agent gets the scope before any 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 read-only list tool with a fully documented 14-parameter schema and annotations covering safety, the description is nearly sufficient — it conveys both the filter surface and the paged nature. Minor gaps: no mention of defaults (per_page=100, order_by ascending) or how to continue paging, though the schema's page description covers the latter.

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%: every one of the 14 parameters has its own description with formats, bounds and cross-references (e.g. client_id from billomat_list_clients). The description merely names filter categories already covered, and notably omits tags, intro, label, article_id, contact_id, per_page and order_by. 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 delivery notes (Lieferscheine)') and enumerates the filter axes (client, status, number, date range, text) plus the paged return shape. It implicitly contrasts with billomat_get_delivery_note via the plural/paged framing, but never names or differentiates from a sibling explicitly.

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

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

Usage is implied by 'filtered by ... ' — an agent infers this is the search/enumerate path versus the single-fetch get_delivery_note. However there is no explicit when-to-use statement, no mention of the sibling get tool, and no guidance on which filters combine or are mutually exclusive.

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 burden is reduced. The description adds only the paging trait ("Paged"), which is also expressed in the schema's page/per_page fields; nothing is said about ordering defaults, empty-result behavior, or how much of the invoice body comes 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?

A single front-loaded sentence with the resource, the disambiguating parenthetical, the filter surface, and the paging note. No filler words to trim.

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, zero-required-parameter list tool with 10 fully documented optional filters and annotations covering safety, the description is nearly sufficient. The only gap is that no output schema exists, so the shape of the returned invoice list is left implicit rather than briefly characterized.

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 every parameter is already documented in structured form. The description's filter recital (supplier, status, number, date range, note, tags) mirrors, but does not enrich, the schema; 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 (List) and resource (incoming invoices), and immediately disambiguates it as supplier-side Eingangsrechnungen, which separates it from billomat_list_invoices (outgoing) and billomat_get_incoming_invoice (single record) 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?

The enumerated filters imply the contexts in which the tool is useful, but there is no explicit when-to-use/when-not statement nor any named alternative (e.g. use get_incoming_invoice for one record). 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds that results are line items/positions, but says nothing about pagination behavior or how empty invoices behave — a modest addition beyond the annotations.

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

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

A single front-loaded sentence naming verb and resource with zero filler; nothing could be trimmed without losing meaning.

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 annotation coverage of safety, the description supplies what an agent needs. It is slightly thin on routing context versus sibling list/get tools, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents page, per_page, and invoice_id fully. 'Of one invoice' reinforces that invoice_id scopes the result, but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('List') plus the exact resource ('line items (positions) of one invoice'), which is precise enough to distinguish from billomat_get_invoice and billomat_list_invoices. It does not explicitly call out those siblings, 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?

No when-to-use guidance, no mention of alternatives (e.g., use billomat_get_invoice for header data, billomat_add_invoice_item to append a position), and no stated prerequisites. Only the phrase 'of one invoice' hints that an invoice id is required.

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 merely restates this as '(read-only)' rather than adding new behavioral context. Nothing is disclosed about pagination behavior, result caps, or authentication needs, so the description adds little beyond the structured fields.

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 with no wasted words. The trailing 'optionally for one invoice, a date range or payment types' is slightly compressed, but overall it is tight and well-structured.

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

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

For a read-only, zero-required-parameter list tool with full schema coverage, the description conveys purpose and available narrowing options adequately. It does not mention pagination or output shape, but with no output schema that omission is minor rather than disqualifying.

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 every parameter (from/to, page, type, user_id, order_by, per_page, invoice_id) is already documented with format and defaults. The description only gestures at the same filters, adding no syntax or format detail beyond the schema, matching the baseline for high-coverage schemas.

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 payments that were recorded on invoices') and scopes it with the available filters. It is distinguishable from siblings like billomat_list_invoices or billomat_list_invoice_items, though it does not explicitly name a sibling to contrast against.

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?

'Optionally for one invoice, a date range or payment types' signals the filtering contexts in which to use it, but there is no explicit when-to-use/when-not or alternative named. 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, so the safety profile is covered. The description adds genuinely new behavioral context — results are paged, and each record includes totals plus the open amount — which matters when 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 compact sentences: the filter inventory first, the paging/return note second. Every clause carries information and nothing is padded.

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, 15-parameter list tool with no output schema, the description covers the filter dimensions and the shape of each returned record (totals, open amount). It does not mention the default page size or pagination limits, though those are documented in the schema, leaving only minor gaps.

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

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

Schema description coverage is 100% across all 15 parameters, and the schema documents formats, defaults and constraints (e.g. yyyy-mm-dd dates, status pattern, per_page bounds) in more detail than the description. The description only restates a subset of filter dimensions, adding no syntax beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List invoices (Rechnungen)') and enumerates the filter dimensions (client, status, number, date range, text, tags), so an agent immediately knows what the tool returns. It does not explicitly distinguish itself from near siblings like billomat_list_invoice_items or billomat_list_recurring_invoices, 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?

The filter list implies when the tool is useful, and the clause 'each invoice carries totals and the open amount' hints at why one would list rather than fetch a single invoice. However, no alternative (e.g. billomat_get_invoice, billomat_invoice_totals) is named and no when-not guidance is given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds 'Paged', signaling pagination, which is useful behavior beyond the annotations. It does not mention default ordering, result caps, or auth/scope 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?

Two compact sentences; the filter list is front-loaded and 'Paged' is a tight trailing signal. Slightly list-heavy but no filler.

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

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

A read-only list tool with full schema coverage and an annotation covering safety is minimally complete enough to call. It lacks usage routing to siblings and any indication of return shape beyond 'Paged', which is adequate but leaves gaps for an agent choosing among list tools.

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 every parameter is already documented with format and range. The description restates the filter categories (client, status, number, date range, text) but adds no syntax beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb (List) and resource (offers/Angebote) with a clear enumeration of filter dimensions. The parenthetical German synonym disambiguates within a sibling set that also contains billomat_list_invoices and billomat_list_confirmations.

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 explicit when-to-use guidance: it doesn't say to prefer billomat_get_offer for a single record, nor when to reach for this vs. a different list tool. The filter enumeration implies it is a filtered browse, but no alternative or precondition is 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=true, so the safety profile is covered. The description still adds the pagination trait ('Paged') and, importantly, enumerates the returned fields in the absence of an output schema, which is genuine added context beyond the annotations.

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

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

A single compact sentence that front-loads the core purpose, then the returned shape, then the pagination note. Every clause carries information and nothing is padding.

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

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

For a 12-parameter, zero-required read tool with no output schema, the description usefully enumerates return fields and notes pagination, which compensates for the missing output schema. It falls short only on usage guidance relative to sibling list tools.

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

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

Schema description coverage is 100%, so all 12 parameters are already documented with types, ranges, and semantics (e.g. next_page usage, per_page default). The description only echoes the cycle enum values and a couple of fields, adding nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb ('List') and resource ('recurring invoices'), adds the German synonym 'Abo-Rechnungen' to remove ambiguity, and names the returned fields (name, cycle, client, next run). It is clearly distinguishable from billomat_list_invoices and the other list_* 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?

Usage is only implied by the resource name; there is no explicit statement of when to prefer this over billomat_list_invoices or billomat_get_invoice. No prerequisites, exclusions, or alternatives are given, so the agent must infer intent.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only 'Paged.', which is genuinely useful context, but says nothing about how filters combine, sort defaults, or what a reminder record 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 sentences, front-loaded with the action and resource, then the filter scope, then the paging note. Nothing is padded or repeated unnecessarily.

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

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

The 15 parameters are fully documented in the schema and there is no output schema to explain, so the description's main job is scoping, which it does. It could still note that filters are combinable and how results are ordered by default.

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

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

Schema description coverage is 100% across 15 parameters, so the schema already documents dates, paging, sorting, IDs and limits. The description only recaps the filter categories (client, status, invoice number, date range, text) without adding syntax or defaults, which is the baseline-3 case.

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

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

The description gives a specific verb and resource ('List payment reminders (Mahnungen)') and enumerates the filter dimensions, so the agent knows exactly what is returned. It never explicitly contrasts itself with the closest siblings (billomat_get_reminder for a single reminder, billomat_list_invoices for the underlying documents), 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?

Naming the available filters implies how the tool is used, but there is no statement of when to prefer it over billomat_get_reminder or billomat_list_invoices, and no note that filters combine. Usage must be inferred from the filter list alone.

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 that this is a non-mutating read, so the description's burden is lower. 'Paged.' adds a genuine behavioral signal about pagination, but nothing is said about defaults, ordering behavior, or that an empty result is possible regardless of filters.

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, filter scope first and pagination last, with zero filler. 'Paged.' is an abrupt fragment, but it is informative rather than padding.

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

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

For a filter-only list endpoint with no required params, no output schema and full schema coverage, the description plus schema are nearly sufficient. The remaining gap is that return shape and page-traversal mechanics rest entirely on the schema's 'Use next_page from the previous reply' note.

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 every one of the 11 parameters is already documented with type, maxLength, pattern and defaults. The description only restates the filter field names (name, email, contact person, country, note, tags) without adding syntax, matching semantics, or combining behavior beyond the schema.

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

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

States a specific verb and resource ('List the suppliers of the account') and enumerates the filterable fields, so an agent can tell it apart from billomat_get_supplier and the other list_* tools by resource. It does not explicitly name a sibling alternative, but the resource noun is unambiguous.

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

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

The description never says when to use this tool versus billomat_get_supplier (single record) or how to retrieve further pages beyond the word 'Paged.' No prerequisites, no exclusions, no alternatives 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?

readOnlyHint=true already establishes this is a safe read operation, so the bar is lower. The description adds one useful behavioral detail - that the default tax rate is included in the result - but says nothing about pagination or result size, which the schema handles instead.

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 short sentence that front-loads the action and resource with zero filler. Every word earns its place.

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

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

For a read-only list tool with fully documented parameters and no output schema, the description covers the essentials: what is listed, for which scope, and that the default is included. It stops just short of describing the return fields, which is a minor gap.

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

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

Schema description coverage is 100%, so page, order_by, and per_page are fully documented in the schema. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

The description gives a specific verb+resource ('List the tax rates (Steuersaetze) of the account') and notes the scope (of the account) plus the inclusion of the default rate. It is the only tax-related tool among the siblings, so no differentiation is needed, but it does not spell out the response shape.

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

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

Usage is implied by the verb 'List' and the account scope, but there is no explicit statement of when to use this versus alternatives. Since no sibling tool covers taxes, the lack of routing guidance is less damaging, leaving it at minimum viable.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lower. The description adds domain context (units apply to article and item quantities) but nothing about pagination behavior, result limits, or ordering defaults 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?

A single sentence that front-loads the core action and scope, with the optional filter appended. Nothing is wasted and nothing is buried.

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

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

For a simple, fully-documented, read-only list endpoint with readOnlyHint annotations and no output schema requirement, the description is nearly complete. It could mention that results are paginated via the next_page pattern, but the schema already covers that.

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, order_by, and name are all fully documented in the schema. The description only nods at the name filter and adds no syntax or format detail beyond the schema, 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 (units used for article and item quantities), plus the available filter. It is trivially distinguishable from the sibling list_articles, list_clients, list_taxes, etc., and the German gloss '(Einheiten)' disambiguates the domain term.

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 'optionally filtered by name' phrasing implies when the filter applies, but there is no explicit when-to-use guidance, no mention of alternatives, and no note about when listing is preferable to fetching individual units. Usage is inferable but not stated.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=true; the description adds genuinely useful context beyond them by clarifying partial-patch semantics ('only the fields you pass are changed; everything else stays') and that no notification is dispatched ('Nothing is sent to the client'). It does not reconcile why a partial, idempotent field update carries destructiveHint=true, which would have been worth addressing.

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

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

Three tight sentences with the WRITE mode marker front-loaded, then the mutation semantics, then the prerequisite. No filler or redundancy.

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

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

For a 19-parameter mutation tool with full schema coverage, existing annotations, and no output schema, the description covers mode, patch behavior, prerequisite, and external side effects. Remaining gaps (error behavior on unknown id, idempotency implications) are minor.

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

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

Schema description coverage is 100% across all 19 parameters, so the schema already carries per-field meaning and the baseline is 3. The description only adds the general rule that unspecified fields are preserved — useful but not field-level detail.

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 ('change fields of an existing client') and a distinguishing scope constraint (partial update; only passed fields change). An agent can separate it from billomat_create_client and billomat_get_client without opening any schema.

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

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

Explicitly prescribes a prerequisite workflow ('Read the client first with billomat_get_client'), which routes the agent to the correct sibling before invoking this one. It stops short of when-not-to-use guidance or alternative update paths, but the operative context is clear.

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