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

The description is consistent with the annotations (readOnlyHint=false, no contradiction) and adds the requirement of entity/items_list and the return value. However, it does not reveal deeper behavioral traits such as auto-creating entities by name or other side effects, which would add value beyond the schema.

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

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

The description is three concise clauses: what it does, prerequisites, and return value. Every part earns its place; 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?

Given no output schema, the description appropriately states that it returns the created document and explains the need for get_company_info. It covers the main use case, though nuances like entity creation by name are left to the schema, which is acceptable given the 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 100%, so the baseline is 3. The description adds the useful clarification that entity and items_list are required (not fully reflected in schema's required array), and points to get_company_info for ID lookups, but otherwise largely echoes schema descriptions.

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 starts with the specific verb 'Create' and identifies the resource as 'issued document' with examples (invoice, credit note, quote). It distinguishes itself from sibling tools like create_received_document by the 'issued' qualifier, and the action 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?

It explicitly states prerequisites ('Requires entity and items_list') and directs the user to get_company_info first for VAT and payment method/account IDs. This provides clear context for use, though it does not explicitly mention when not to use it or alternatives like update_issued_document.

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 behavioral context by specifying required fields (description, entity, date, amounts) and a key validation rule: payments_list must cover the total. It also states the return value (created document). Annotations already indicate a non-read-only operation, and the description does not contradict them.

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 and front-loaded with the purpose. It uses two sentences with no unnecessary words, efficiently conveying the essential requirements and return 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?

Considering the tool's complexity (nested objects, many optional fields), the description covers the most critical aspects: required fields, total coverage rule, and return value. It does not mention company_id or all subfields, but the schema and annotations fill those gaps adequately.

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

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

The description enhances schema semantics by emphasizing required fields for creation and the constraint that payments_list must cover the total. Even though schema has 100% coverage, the description clarifies the purpose and necessity of these fields, adding value beyond the field names.

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 'Create a received document' with the specific verb 'Create' and resource 'received document', explicitly listing subtypes like expense and passive credit note. This distinguishes it from the sibling tool create_issued_document, which handles issued documents.

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

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

The description implies usage for creating received documents (expenses, credit notes) but does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool references are provided, making the usage guidance implicit rather than explicit.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds valuable context: 'Irreversible' reinforces the destructive nature, 'the document itself is untouched' scopes the effect, and the note about the FIC API returning 500 discloses a real behavioral risk. This goes beyond what annotations provide.

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

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

Two concise sentences. The first states purpose and scope; the second provides critical caveats and alternatives. No unnecessary words. Front-loaded and easy to parse.

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

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

The description covers purpose, scope, irreversibility, API instability, and alternatives. It lacks explicit mention of what happens on success (e.g., return value) and whether the tool deletes a single attachment or all attachments when a document might have multiple. However, given the simplicity of the tool and the absence of an output schema, the provided information is largely 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 coverage is 100% with detailed descriptions for all parameters, so the baseline is 3. The description does not add much parameter-specific meaning beyond what the schema already explains (target enum, company_id default behavior, document_id). No extra detail is needed beyond the schema.

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

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

The description clearly states the action: 'Remove the attachment from an issued or received document' with a specific verb and resource. It also clarifies that 'the document itself is untouched', distinguishing it from document deletion tools like delete_issued_document and delete_received_document. The scope is explicit.

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 names alternatives: 'deleting the document or replacing the attachment via update (new attachment_token) are alternatives.' This gives clear when-to-use guidance versus sibling tools. It also notes the API's observed 500 behavior, cautioning the user. The context of removing just the attachment while keeping the document is implicit but clear.

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

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

The description adds 'Irreversible' and 'Permanently', which reinforce the destructiveHint annotation and provide additional context about the consequence of deletion. It does not contradict annotations and adds value by warning the user about the non-recoverable nature, though it doesn't disclose other behavioral details like auth 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?

The description is extremely concise, using only two short sentences. Every word is purposeful, with the key action and consequence front-loaded. No redundant or unnecessary 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 simple delete tool with two well-described parameters and annotations conveying destructive and idempotent hints, the description is sufficient. It covers the purpose, method, and consequence. It could theoretically mention error cases or return behavior, but for a deletion operation this is largely optional.

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 descriptions cover both parameters at 100%, so the description adds little beyond what the schema already provides. The phrase 'by ID' aligns with the document_id parameter but does not introduce new semantic details.

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: 'Permanently delete an issued document by ID.' It uses a specific verb (delete), identifies the resource (issued document), and specifies the parameter (by ID). This distinguishes it from sibling tools like get_issued_document and update_issued_document.

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 the tool (when you need to delete an issued document by ID) but provides no explicit guidance on when not to use it or mention of alternatives. There is no reference to sibling tools or exclusions, so it falls short of a 4.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds 'Permanently delete' and 'Irreversible,' reinforcing the permanent nature and explicitly stating no undo capability, which adds value beyond the annotations. It does not contradict 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 sentence with no fluff. It immediately conveys the action and consequence ('Irreversible'), making it easy to parse.

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

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

For a simple delete operation with two well-documented parameters and no output schema, the description is adequate. It mentions permanence and irreversibility. However, it could briefly note side effects (e.g., if attachments are deleted) or mention that it works only for received documents, but this is 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%: both 'company_id' and 'document_id' are described in the schema. The description does not add additional parameter meaning beyond what the schema already provides, so 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: 'Permanently delete a received document by ID.' It specifies the verb, resource type, and uniqueness (received document vs issued document), distinguishing it from sibling tools like delete_issued_document.

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 tool name and description (to delete a received document), but there is no explicit guidance on when to choose this over alternatives, such as delete_issued_document or update_received_document. No exclusions or prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that it returns configuration lists and hints at VAT type usage in items_list, but does not disclose return format, pagination, or error behavior. Given the annotation, 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?

A single, front-loaded sentence that immediately states the tool's purpose and enumerates the available lists. There is no redundant or filler content; 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?

The tool is simple (2 parameters, no nested objects, no output schema) and the description covers what it does, what data it returns, and the use case. The schema fully documents parameters, and readOnlyHint covers the safety aspect. Nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by noting 'VAT types (IDs for items_list)', linking the resource enum to document building. This enhances understanding of what the returned data will be used for.

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 a specific action ('Look up company configuration') and resource ('needed to build documents'). It enumerates the actual configuration lists (VAT types, payment methods, payment accounts, expense categories), making its purpose distinct from sibling document CRUD tools and list_companies.

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

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

The phrase 'needed to build documents' provides clear context for when to use this tool. It does not explicitly mention alternatives or exclusions, but the context sufficiently implies when this tool is appropriate relative to sibling document-related 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?

With readOnlyHint=true already provided, the description adds value by disclosing the response content (entity, line items, payments, amounts) which is especially useful since there is no output schema. It does not contradict annotations and gives insight into what the agent will receive.

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, front-loaded sentence that clearly states the verb, target, and key details. There is no fluff or repetition; 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 simple getter with full schema coverage and read-only annotation, the description is complete. It mentions the core purpose and return content. Missing explicit references to optional parameters (fieldset, company_id) but these are well-covered in the schema, so no significant gap remains.

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 baseline is 3. The description's mention of 'by ID' adds no new meaning beyond the schema's document_id description. It does not elaborate on fieldset or company_id, but these are already fully documented in the schema.

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

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

The description clearly states 'Get a single issued document by ID' with a specific verb and resource, and it enumerates the returned details (entity, line items, payments, amounts). This distinguishes it from siblings like list_issued_documents (collection) and get_received_document (received vs. issued).

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

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

The description implies usage for fetching one specific document by ID, which is clear given sibling names and the word 'single'. However, it does not explicitly mention alternatives such as list_issued_documents for multiple documents or when not to use this tool, but the context is strong enough.

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

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

The readOnlyHint annotation already declares this is a safe read, so the description does not need to repeat that. It adds some domain context ('expense, passive credit note') and 'with full details', but does not disclose other behavioral aspects like error handling, required permissions, or the meaning of 'full details' relative to the fieldset parameter. No contradiction with 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 sentence of about 14 words, front-loaded with the verb 'Get'. It includes the resource type and the key qualifier 'by ID' without any redundant phrasing. Every word 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?

For a simple get-by-id tool with 3 parameters (one required) and full schema coverage, the description provides adequate context: it identifies the resource type, the scope, and the default detail level ('full details' aligns with the default fieldset 'detailed'). However, it does not mention the fieldset option explicitly, though the schema covers that. Overall, it is complete enough for an agent to use correctly, especially given the annotations.

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 parameters are fully documented in the schema. The description adds no parameter-level information; it only references 'by ID', which maps to document_id. The fieldset and company_id parameters are not mentioned in the description, but the schema already explains them adequately.

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 'Get a single received document... by ID', which specifies the action, resource, and scope. It distinguishes from siblings like get_issued_document (received vs issued) and list_received_documents (single vs list), and clarifies the domain by naming examples like 'expense, passive 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?

The description gives clear context: this is for retrieving one document by ID, implying you already have a document_id. It does not explicitly mention alternatives or exclusions, but the phrase 'single... by ID' effectively communicates when to use it vs list tools. Lacks an explicit pointer to list_received_documents for listing or get_issued_document for issued 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 declare readOnlyHint=true, and the description adds valuable context by specifying the return fields (id, name, type) and explaining the id's role as company_id. This goes beyond the annotation 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 exactly two sentences with no fluff. The first sentence states the action, the second clarifies the output and its significance, making it appropriately front-loaded and concise.

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

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

For a simple zero-parameter, read-only list tool, the description fully covers the purpose, scope, output, and how the result integrates with other tools. No output schema exists, but the description adequately compensates without leaving major 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?

The tool has zero parameters, so the baseline is 4. The description correctly adds no parameter information, and there is nothing else needed.

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 lists companies accessible with the configured token, using a specific verb and resource. It distinguishes itself from sibling tools by focusing on companies and explaining that the returned id is the company_id used by other 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 implies the tool should be used to obtain company IDs needed for other tools, providing direct usage context. It does not explicitly exclude alternatives or mention when not to use it, but the purpose is clear enough.

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

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

Annotations already declare readOnlyHint=true, so the safe read nature is covered. The description adds meaningful behavioral details beyond that: pagination behavior (check current_page/last_page/total) and the one-type-per-call restriction with a default type. This informs the agent about response structure and call constraints.

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 primary purpose ('List issued documents'), and includes only essential operational hints (type default, pagination). No redundant or filler content—every 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 read-only list tool with 7 fully documented parameters and no output schema, the description covers the key aspects: what is listed, the type constraint, and the pagination response fields. It does not mention return fields or alternatives, but the schema and annotations fill most gaps, making it adequately complete for a list operation.

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

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

Schema description coverage is 100%, with all 7 parameters documented in detail. The description itself only reiterates the default to invoices and mentions pagination, which adds minimal new parameter-specific meaning. Baseline of 3 is appropriate when the schema fully handles parameter semantics.

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 lists issued documents, enumerates common document types (invoices, credit notes, quotes, proformas, receipts), and distinguishes it from sibling tools like list_received_documents and get_issued_document. The verb 'List' plus resource 'issued documents' with scope 'for a company' makes 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 provides clear usage context: one document type per call (defaults to invoices), paginated results requiring checking current_page/last_page/total. It does not explicitly mention when to use get_issued_document for a single document or list_received_documents for received documents, so it lacks explicit alternatives but gives solid operational 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?

With readOnlyHint=true in annotations, the safety profile is already known. The description adds behavioral value by disclosing the default type (expenses) and the pagination behavior (check current_page/last_page/total). These details go beyond the annotation and help the agent understand response structure and defaults.

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 and front-loaded. It uses three short sentences, each adding new information: the list of document types, the default type, and pagination guidance. No word is wasted, making it efficient and easy to parse.

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

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

For a list tool with no output schema, the description provides the key context: the resource type, available document types, default behavior, and pagination metadata fields. While it does not explicitly state the return format (e.g., array of documents), it is implied by the title and the pagination hint, and the schema covers all parameters. This is adequate for the complexity level.

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, so every parameter is already documented. The description adds no extra parameter semantics beyond what the schema provides; even the 'Defaults to expenses' note repeats the schema's default for 'type'. Therefore, a baseline score of 3 is appropriate.

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

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

The description states the exact action: 'List received documents for a company' and enumerates the document types (expenses, passive credit notes, passive delivery notes, self invoices). This specifies the resource and scope, distinguishing it from sibling tools like list_issued_documents or get_received_document.

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 context (for a company, defaults to expenses, paginated) but does not explicitly contrast with alternatives such as get_received_document for single documents or list_issued_documents for issued documents. Usage is implied by the tool name and listing of types, but no exclusions or alternative guidance 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?

Annotations already disclose that this is not read-only and is potentially destructive. The description adds valuable behavior beyond the annotations: the partial update behavior ('Only the fields provided in data are changed') clarifies that unspecified fields are not wiped, which is essential for understanding the destructive scope. No contradiction with annotations is present.

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 action and resource. The second sentence adds essential usage guidance without any fluff. Every word earns its place, making it both concise and highly informative.

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 moderately complex update tool with no output schema, the description covers the core purpose, partial update behavior, and a necessary prerequisite. The rich input schema already documents all parameters, so the description does not need to repeat that. It could mention error handling or return values, but those are not critical given the schema completeness and annotations.

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

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

Schema coverage is 100%, so all parameters are described in the schema. The description adds meaning beyond the schema by explaining that the `data` object is a partial update (only provided fields changed), which affects how all nested fields inside `data` should be interpreted. This is a key semantic that the schema itself does not explicitly state.

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 action ('Update an existing issued document') with a clear resource, and distinguishes itself from create/delete/get operations by focusing on modification. It also clarifies partial update semantics ('Only the fields provided in data are changed'), leaving no ambiguity about the tool's role.

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 explicit usage context by instructing the user to fetch the document first with get_issued_document to see its current state, which is a clear prerequisite for safe updates. It does not explicitly mention alternatives (like create or delete), but the naming and sibling tool list make those distinctions obvious. The instruction gives clear when-to-use guidance without exclusions.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=true, and the description adds crucial context: only provided fields are changed (partial update), which clarifies the destructive nature (only changing specified fields). It also advises fetching first, which mitigates destructive actions. No contradiction with 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, front-loaded with the action, and every word earns its place. The instruction to fetch first is practical and includes a sibling tool name. No redundancy or 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?

Given the tool's complexity (nested objects, optional fields, no output schema), the description covers the core update semantics and the key prerequisite (fetch first). It doesn't detail return values or error scenarios, but the schema and annotations fill in much of the context. For an update tool, this is adequately complete, though a note on return values would push it to 5.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaning to the 'data' parameter by clarifying that only provided fields are changed, which is a significant semantic beyond the schema. This compensates for the lack of per-parameter elaboration, earning a 4 rather than 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 states a specific verb ('Update') and resource ('existing received document'), clearly distinguishing it from create/delete siblings. It also implies the scope (expense) via the title, and mentions the need to fetch first, reinforcing the update use case.

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

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

The description gives explicit guidance to fetch the current state with get_received_document before updating, which is a clear when-to-use instruction. It doesn't explicitly state when not to use this tool versus update_issued_document, but the resource type is clear from the name and siblings. The guidance is sufficient for correct tool selection.

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 indicate it's a non-read, non-idempotent, non-destructive operation. The description adds behavioral context by revealing that tokens expire ('Unbound tokens expire after a while') and advising timely upload, which goes beyond the annotation basics.

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 action, and every sentence carries essential workflow information. No redundancy or 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 tool with 4 parameters and no output schema, the description explains the return value (attachment_token) and the binding workflow, which is essential for correct use. It omits details like error handling or cleanup, but those are not critical given the schema handles 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 all parameters are already documented. The description does not add parameter-specific details beyond that, but it does mention file types ('PDF, image, XML, zip...') which coarsely aligns with file_path. This meets the baseline for schema-heavy 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: 'Upload a local file... as an attachment for an issued or received document.' It also explains the return of an attachment_token and its binding role, distinguishing it from sibling 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 description provides workflow guidance: 'pass it as data.attachment_token in a create/update tool' and 'upload right before creating/updating'. It does not explicitly state when not to use, but the usage context is clear and actionable.

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