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

Annotations already mark destructiveHint=true, but the description adds the irreversibility warning and instructs to confirm the document number with the user. This is valuable behavioral context beyond the annotations, specifying a safety precaution.

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

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

The description is two sentences with no fluff. It front-loads the core purpose, then adds the critical irreversibility warning. 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?

It provides essential context: the only way to void, irreversibility, and a user-confirmation requirement. It doesn't describe success/failure behavior but that's acceptable for a cancellation tool, and the output schema is absent. The description is sufficient for correct invocation.

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

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

Schema description coverage is 75% (doctype has no description but has enum). The description adds no parameter-specific information—it doesn't elaborate on docnum, reason, or refundCc. Since the schema already covers most parameters, a baseline of 3 is appropriate.

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

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

The description clearly states the action: "Cancel an existing document". It further differentiates from siblings by noting iCount has no hard delete and this is the only way to void one, which distinguishes it from close, convert, or other document operations.

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

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

It explicitly states this is the only way to void a document, giving strong usage context. It doesn't name alternative tools but the statement implies when to use (when voiding) and when not (for other operations). This is clear enough for an agent to select it appropriately.

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 annotations indicate non-readonly, non-destructive, open-world, non-idempotent. The description aligns: it marks as closed/paid, which is a mutation but not destructive. It adds meaningful context: linking base documents settles them, implying a relationship update. It does not contradict; it clarifies the state transition and the optional linkage, which is beyond what annotations convey.

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

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

The description is a single, concise sentence that captures the core functionality and the key optional aspect (linking base documents) without extraneous detail. It is front-loaded with the primary action and outcome. No wasted words.

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

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

Given the tool's moderate complexity (3 params, nested objects in basedOn), the description is quite complete. It does not describe return values (no output schema), but that is acceptable. It covers the main purpose and the optional behavior of basedOn. It lacks details on edge cases or side effects, but for a closure operation, the description sufficiently informs the agent.

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

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

Schema coverage is 67%: doctype and docnum are documented in the schema with descriptions ('The document number as shown in iCount'). The description adds value for 'basedOn' by explaining its purpose ('Base documents this closure settles, e.g. an offer this order fulfills'), which goes beyond the schema's 'Base documents this closure settles'. However, it does not clarify the exact structure of 'basedOn' beyond what schema provides.

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

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

The description clearly states the action ('Mark a document as closed/paid') and the resource ('document'), with a specific outcome. It distinguishes from siblings like icount_cancel_document (cancels vs closes) and icount_convert_document (converts vs closes) implicitly, though it does not explicitly name alternatives. The verb 'Mark' is specific enough to indicate a state change rather than full deletion or creation.

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

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

The description gives a clear sense of when to use it: to close a document, optionally linking base documents. It distinguishes from creation and cancellation by context, but it does not explicitly state when not to use it (e.g., for cancellation) or name alternatives. It implies usage in the context of finalizing a document after it is paid or fulfilled.

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

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

Annotations already indicate this is a mutating, non-idempotent operation. The description adds the discovery mechanism (listing options first), which is a behavioral trait beyond annotations. However, it does not disclose side effects such as whether the original document is modified or if a new one is created, nor does it mention error conditions. With annotations present, the added value is moderate, so a 3 is appropriate.

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

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

The description is two sentences with zero filler. It front-loads the primary action, then immediately explains the necessary two-step usage. Every sentence earns its place, making it highly concise and well-structured.

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

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

The description covers the essential usage pattern completely, including the discovery step and the actual conversion. It does not detail return values (no output schema) or prerequisites like document existence, but these are not critical for an agent to invoke the tool correctly. The two-step workflow is fully explained, which is the main complexity.

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

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

Schema coverage is 67% (docnum and conversionType have descriptions; doctype is only an enum). The description adds critical semantics for conversionType by explaining the two-step workflow, which goes beyond the schema's simple 'value returned by a prior call'. This enriches the parameter understanding and justifies a score above the baseline 3.

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

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

The description clearly states the action (convert a document to another type) with a concrete example (offer -> order). It distinguishes this tool from siblings like create, cancel, or close because conversion is a unique operation. The verb and resource are specific and 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 explicitly explains the two-step usage pattern: omit conversionType to list valid options, then pass one back to perform the conversion. This is clear guidance on how to invoke the tool correctly. While it doesn't mention alternatives, the operation is distinct from sibling tools, so no exclusion is needed.

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

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

Annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the description does not need to restate these. It adds a minor behavioral distinction ('without also creating a document') but does not disclose potential side effects (e.g., whether a client ID is returned, or any uniqueness constraints). This is adequate but not rich.

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

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

The description is a single, concise sentence that front-loads the core action and key distinction. There is no wasted text, and it is easy to parse quickly.

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

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

For a create operation with 10 parameters and no output schema, the description is minimal but functional. It does not mention return values (e.g., the new client ID) or potential errors, and it does not point to related tools for verification. Given the complexity, more guidance (e.g., noting that the client ID is returned and can be used in subsequent calls) would improve completeness.

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

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

Schema description coverage is only 40% (name, vatId, paymentTerms, customClientId have descriptions). The tool description adds no extra meaning for the remaining six parameters, such as `paymentTerms` interpretation or `customClientId` usage. Given the low coverage, the description should compensate but does not, leaving agents dependent on parameter names alone.

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

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

The description clearly states the action ('Create a new client/recipient record') and explicitly distinguishes it from creating a document. This differentiates it from sibling tools like icount_create_document, making the purpose unambiguous.

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

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

The description implies when to use this tool ('directly, without also creating a document'), signaling this is the right choice when only a client record is needed. However, it does not explicitly mention alternatives like icount_update_client for existing clients or note any prerequisites, leaving some inference to the agent.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds valuable behavioral context: iCount has no hard delete (only cancel), and tax documents are rejected without a payment breakdown. It also implicitly warns that creation may have side effects (email sending, no deletion). It doesn't mention rate limits or auth, but the annotations cover the safety profile, so a 4 is appropriate.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence earns its place. The first sentence states what the tool does; the second provides critical usage guidance. No fluff, no repetition of schema details.

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

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

For a complex tool with 16 parameters, nested objects, and no output schema, the description covers the most important behavioral constraints (payment requirement, no hard delete, testing preference). It doesn't describe the return value, but with no output schema, that's a gap. However, the description is strong enough on the critical decision points that an agent can call it correctly. A 4 is fair.

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

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

Schema description coverage is 75%, so the schema already documents most parameters. The description adds meaning beyond the schema by explaining the payment requirement for tax documents and the testing preference for non-tax types. It also clarifies the relationship between clientId and clientName (reuse vs. create/match). This is meaningful added value, though the schema still carries most of the parameter documentation burden.

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

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

The description states a specific verb ('Create') and resource ('a document in iCount'), enumerates the document types, and distinguishes this tool from siblings like icount_cancel_document and icount_convert_document. It also adds practical guidance about which doctypes to prefer for testing, which makes the purpose even clearer.

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

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

The description explicitly says when to use this tool (creating any iCount document) and gives concrete guidance: prefer non-tax types (order/offer) for testing because iCount has no hard delete, and real tax documents (receipt/invrec) require a payment breakdown or they will be rejected. This is actionable and goes beyond generic 'use this to create documents'.

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 state destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral context: the delete is 'real, irreversible,' requires user confirmation, and should only be used for clients without associated documents. This goes beyond the annotations and gives the agent actionable safety 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, front-loaded with the core purpose and then adding necessary caveats. Every word earns its place; there is no redundant filler or repetition of schema/annotation data.

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

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

The description covers purpose, irreversibility, confirmation, and usage constraints, which is strong for a simple one-parameter delete tool. However, it does not explain what happens if called on a client that does have associated documents (e.g., error, cascade, or block). Since no output schema exists, a brief note on expected outcome would make it fully complete.

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

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

Schema description coverage is 0%, so the description must compensate for the sole parameter, clientId. The description does not explicitly define clientId, but its meaning is implied by the tool name and purpose ('delete a client record'). This is adequate for a single obvious parameter, but the description adds no explicit parameter-level detail such as format or source.

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 begins with a specific verb and resource: 'Permanently delete a client record.' It also distinguishes this tool from document-related operations by noting 'Unlike documents, this is a real, irreversible delete,' which differentiates it from sibling tools like cancel_document or close_document. The scope 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 provides clear conditions for use: 'confirm with the user first' and 'prefer it only for clients with no associated documents.' This gives an explicit when-not condition. However, it does not name an alternative tool (e.g., update_client) for cases where deletion is not appropriate, so it falls short of full alternatives guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the result contains 'full details', which is a useful expectation of the output, but it does not discuss errors, rate limits, or other behavioral traits.

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

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

The entire description is one short sentence with no filler. It is front-loaded with the action and object, making it easy to scan.

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

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

For a simple read operation with one parameter and annotations covering safety, the description is adequate. It communicates the return scope ('full details') but does not describe the exact fields or error cases, which is a minor gap given the lack of 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?

The schema only defines clientId as a non-empty string; the description's 'by id' clarifies that this parameter is the client identifier. It adds little beyond that, leaving the source or format of the id unspecified.

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 the verb 'Fetch' and the resource 'full details of a single client by id', clearly distinguishing this from sibling list or search tools. The phrase 'single client by id' differentiates it from list_clients and get_client_open_docs.

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

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

The description provides no explicit guidance on when to use this tool over alternatives like list_clients or get_client_open_docs. It only describes the operation, leaving the agent to infer that it should be used when a specific client id is known.

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

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

Annotations already cover the read-only, idempotent, and non-destructive nature of this tool. The description adds value beyond annotations by stating that a client identifier is mandatory, defining 'open' as unpaid/unsettled, and disclosing the absence of an all-clients mode. It also clarifies that the result represents an outstanding balance, which is useful operational context.

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

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

The description is three sentences long and front-loaded with the core purpose, followed by identifier options and the sibling alternative. There is no filler, and every sentence contributes to correct tool selection and invocation.

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 5-parameter tool with no output schema, the description covers the key operational constraints: mandatory client reference, no all-clients mode, and the meaning of 'open'. It does not detail the response shape beyond outstanding balance, but the core use case and invocation requirements are sufficiently specified.

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

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

With 80% schema description coverage, most parameters are already documented in the input schema. The description adds extra meaning by marking clientId as the preferred identifier and presenting email/clientName as alternatives, which is not obvious from the schema's 0 required parameters. It does not cover doctype, but the enum provides sufficient constraints.

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

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

The description states a specific verb and resource ('List one client's open documents') and further clarifies 'open' as unpaid/unsettled. It explicitly differentiates from the sibling icount_search_documents by noting there is no all-clients mode and directing the agent to that alternative. This makes the tool's purpose distinct from icount_get_document and icount_list_clients.

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

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

It gives explicit when-to-use guidance: the caller must provide one of clientId, email, or clientName, with clientId preferred. It also provides a when-not condition by stating 'There is no all-clients mode; for that, use icount_search_documents with status 0.' This clearly orients the agent among 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 communicate read-only, idempotent, non-destructive behavior, so the description does not need to restate safety. It adds only that the document must already exist, without describing response shape, error behavior, or the effect of the optional flags. This is adequate but not rich contextual 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?

A single sentence that front-loads the core action and identifier without extraneous phrasing. 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 fetch by known identifiers, the description is nearly sufficient: it states scope and identity, while optional parameters are explained in the schema. It falls slightly short because there is no output schema and the description only vaguely promises 'full details' without hinting at the response or failure behavior.

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

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

Schema description coverage is high (80%), and the schema already documents doctype, docnum, getItems, getPdfLink, and getPayments with their defaults. The description reinforces that doctype/docnum identify the document but adds no additional meaning beyond the schema, matching the baseline for high schema coverage.

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

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

The description names a specific verb ('Fetch'), a clear resource ('a single existing document'), and the identifying criteria ('by type and number'). It distinguishes this from siblings like search_documents (search vs exact fetch) and get_document_url (URL only vs full details).

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

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

The description implies the right context: use when you already know the doctype and docnum and want the full object, rather than when searching or listing. However, it never explicitly names alternatives or says when not to use it, so the usage guidance remains implicit.

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 annotations already providing readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds useful behavioral context by clarifying that the operation returns a viewable/printable PDF URL rather than a document payload or a rendered PDF file. It also implicitly confirms no write side-effects are involved, consistent with the annotations.

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

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

The description is a single clear sentence with no filler. It front-loads the core action ('Get'), the resource ('URL (PDF)'), and the condition ('existing document'), earning every word.

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

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

Given the rich schema (7 parameters, enums, high coverage) and the presence of safety annotations, the description covers the essential return nature (PDF URL) and scope (existing document) without needing to restate schema details. It would benefit from mentioning whether the URL is temporary or persistent, but the core knowledge needed for correct selection and invocation is present.

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

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

Schema description coverage is 86%, so the input schema already documents most parameters. The description itself does not add parameter-level meaning beyond indicating the output is a PDF URL, but with such high schema coverage, that is acceptable at the baseline level.

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 ('Get') and resource ('viewable/printable URL (PDF) for an existing document'), clearly distinguishing it from sibling tools like icount_get_document, which returns document data rather than a PDF URL. The phrase 'existing document' also narrows the scope and prevents confusion with create/update tools.

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

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

Usage context is implied: use this when you need a PDF URL for an already-existing document. However, the description does not explicitly state when not to use it or name alternatives, so an agent must infer the choice from sibling tool names and context signals rather than receiving direct routing guidance.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value by revealing the return shape and explicitly warning that results can be truncated, which helps the agent interpret the response.

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 focused sentence communicates both the core operation and the return envelope. No filler or redundant 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 simple list tool with two optional, well-documented parameters and no output schema, the description plus annotations are largely sufficient. It would benefit from hinting about pagination or alternative tools, but that is not a major gap 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?

The input schema has 100% description coverage for maxResults and detailLevel, so the description does not need to repeat parameter details. It adds no deeper semantics beyond implying that returned/truncated counts matter, which is already suggested by 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?

Description states a specific verb and resource: 'List clients in the account.' This clearly distinguishes it from sibling operations like create/update/get/delete client and from broader document tools.

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

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

The account-level scope gives clear context for when to use it: when you need to enumerate clients in the account. It does not explicitly name or exclude sibling tools, but the purpose is clear enough to route an agent appropriately.

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

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

The description adds valuable behavioral context beyond the annotations: it specifies the exact empty-result format (`{ docs: [], matched: 0 }`) and explains that a broad date range may be rejected as `too_many_results`, with guidance to narrow rather than increase maxResults. This complements the readOnlyHint, openWorldHint, and idempotentHint annotations without contradiction.

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

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

The description is concise (two sentences) and front-loaded with the core purpose. The second sentence delivers crucial usage warnings without unnecessary fluff. Every sentence earns its place, making it efficient for an agent to parse.

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

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

Given the tool has 14 parameters and no output schema, the description covers the essential usage constraints (at least one filter, empty-result format, too_many_results handling) but leaves parameter-level details to the schema, which is only 43% covered. It does not explain response structure beyond the empty case, nor does it clarify defaults for maxResults or detailLevel (though those are in schema descriptions). It is adequate but not comprehensive for such a parameter-rich tool.

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

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

With only 43% schema description coverage, the description should compensate for the many undocumented parameters (vatId, docnum, clientId, clientName, clientEmail, sortField, sortOrder). It only lists filter categories generically (type, status, client, date range, document number) without explaining individual parameter semantics or their relationships. This is insufficient given the low coverage.

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

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

The description clearly states the tool's function: searching existing iCount documents by multiple specific filter criteria (type, status, client, date range, document number). It distinguishes itself from siblings like icount_get_document (which retrieves a single document) and icount_get_client_open_docs (which is client-specific), making the purpose unambiguous.

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

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

It explicitly states that at least one filter is required, which is a key usage constraint. It also advises on handling 'too_many_results' by narrowing the date range rather than raising maxResults. However, it does not explicitly mention when to use this tool versus alternatives (e.g., using icount_get_document for a known document ID), though the purpose is clear enough that an agent can infer it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the call fetches basic app/account info, but does not disclose error behavior or what exactly is returned. This is acceptable for a simple health-check tool but not rich 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 sentence conveys the purpose, target, and method with no filler or repeated information. 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 zero-parameter connection test with annotations covering side effects, the description is complete: it states what is verified and how. No output schema exists, but the description's mention of 'basic app/account info' gives sufficient context about the likely return value.

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 has zero parameters and schema coverage is 100%, so there is no parameter burden for the description to carry. This matches the baseline 4 for parameterless tools; the description does not need to compensate for missing schema information.

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

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

The description clearly identifies the action ('Verify'), the specific resource ('configured iCount API token'), and the mechanism ('fetching basic app/account info'). This is distinct from all sibling CRUD/document tools and is not a tautology of the tool name.

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

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

The description makes the connection-testing purpose obvious and clearly separates it from the document/client operations listed as siblings. It does not explicitly state 'use this before other calls' or name exclusions, but the context is clear enough that an agent would know when to use it.

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

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

Annotations already mark this as a non-read-only, non-destructive, idempotent operation. The description adds the important behavioral trait that only provided fields are changed, preventing an agent from assuming a full replace. It does not cover error handling or side effects, but the annotation coverage lowers the bar and the partial-update statement is meaningful.

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

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

The description is two short sentences, front-loaded with the main action and followed by a crucial caveat. There is no repetition of schema details or unnecessary context, so 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?

Given the 11 parameters and no output schema, an agent still needs to know which identifier to use when both clientId and customClientId exist, and what the response indicates. The description covers the core update operation but leaves these operational details to inference, making it adequate but not comprehensive.

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

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

Schema description coverage is only 27%, with 8 of 11 parameters having no descriptions. The description does not explain individual field meanings, such as the difference between phone and mobile or the semantics of customClientId, and it fails to compensate for the low coverage. The partial-update concept is helpful but does not resolve field-level ambiguity.

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

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

The description uses a specific verb ('update') and resource ('existing client'), making the tool's purpose unambiguous. It also adds the partial-update qualifier 'Only fields provided are changed,' which differentiates it from create or replace operations among the sibling tools.

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

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

The description clearly implies this tool is for modifying an existing client, which is enough to distinguish it from icount_create_client or icount_delete_client. However, it does not explicitly state when not to use it or name any alternative tools, so it falls just short of full guidance.

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