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

Annotations only indicate non-read-only and non-idempotent behavior. The description adds that the API performs authoritative fiscal validation, can optionally submit through a provider integration, and requires prior onboarding/configuration. This goes beyond the structured hints, though it doesn't cover failure behavior or response format.

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, front-loaded with the primary function and followed by operational context. Every sentence earns its place without 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?

This is a complex create tool with a large nested input and no output schema. The description covers high-level behavior and prerequisites but omits return value, validation failure behavior, and how the 'integration' object affects submission. More operational context would help the agent invoke it correctly.

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

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

The schema covers 50% of top-level parameters with rich nested descriptions for 'data', so the schema does much of the work. The description contributes no parameter-specific guidance and doesn't compensate for undocumented top-level parameters like site_url, site_title, and plugin_version.

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 a specific verb and object: 'Generate a Polish KSeF FA(3) XML invoice or credit note.' It clearly identifies the document format and distinguishes this tool from siblings like SDI, Zugferd, and Peppol.

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: it performs authoritative KSeF fiscal validation and can optionally submit via the configured provider, with a prerequisite that onboarding/legal-entity configuration be completed. It doesn't explicitly name alternatives or state when not to use it, but the Polish KSeF scope is evident from the title and first sentence.

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 already indicate a non-read-only, non-idempotent operation. The description adds valuable behavioral context: it mentions the Basic+ plan requirement for email delivery, the ability to generate an HTML version, and the return type (PDF binary or JSON). It also explains the data.pdf configuration structure. These go 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?

The description is well-structured with a summary, detailed configuration list, and return statement. It is appropriately sized for a complex tool. Minor redundancy exists between the first sentence and the second sentence ('Generate a PDF invoice' vs 'Creates a printable PDF invoice'), but overall every section 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 complex nested data object, the description does a good job of pointing the agent to the crucial data.pdf configuration and the email delivery option. It mentions the return types, which is important because there is no output schema. It could be more explicit about required prerequisites, but the schema 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 50%, and the description lists key data.pdf fields, but this mostly mirrors the schema's own descriptions (e.g., invoice_html, logo_url, email_invoice). It adds a consolidated view but does not introduce new semantics beyond the schema. The send_email parameter is described in both places, with the schema slightly more detailed.

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: 'Generate a PDF invoice with optional branding and email delivery.' The verb 'generate' is specific, the resource is a PDF invoice, and it distinguishes itself from sibling tools like pop_create_sdi_invoice or pop_create_peppol_invoice by focusing on PDF 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 clear context: it's for creating printable PDF invoices, optionally with email delivery. It implies when to use this tool (when a PDF, not an SDI/KSeF/Peppol document, is needed) but does not explicitly name alternatives or provide exclusion criteria. Still, the context is unambiguous.

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

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

Annotations indicate this is a non-read-only, open-world operation, and the description adds relevant behavioral context: it generates UBL 2.1 XML, optionally submits to the Peppol network, and returns either a UBL XML string or a JSON with UUID. It also discloses the integration/prerequisites for submission. 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 well-structured with a clear top-line purpose, a short explanation of Peppol, a bulleted 'Restrictions' section, a return-value note, and an 'Args' list. It is not overly verbose, though the Args section partially repeats schema information; still, 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 complex tool with 7 parameters, nested objects, and no output schema, the description covers purpose, format, return types, integration requirements, and key restrictions. It does not describe every nested field, but the schema handles that. The missing output schema is compensated by the explicit return 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?

The description highlights the key parameters 'data', 'submit_to_peppol', and 'integration' with meaningful semantics beyond the schema, such as the customer_type restriction inside 'data' and the condition for 'submit_to_peppol'. Schema coverage is 57%, and many nested fields are documented in the schema, so the description adds useful high-level guidance without repeating every 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?

The description opens with a specific verb+resource: 'Generate a Peppol e-invoice in UBL 2.1 format and optionally submit it to the Peppol network.' It names the format, the network, and the action, and is clearly distinct from sibling tools like pop_create_sdi_invoice or pop_create_zugferd_invoice.

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 states when to use this tool (Peppol e-invoicing) and provides explicit restrictions: customer type must be 'company' or 'freelance', submission requires an active Peppol via POP integration, and the customer needs a valid Peppol participant ID. It does not explicitly name alternative tools for other formats, but the context 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 indicate a write operation (readOnlyHint=false) with possible external side effects (openWorldHint=true). The description adds substantial context: it creates a compliant XML document, can submit to SdI, requires a specific plan, and returns either an XML string or JSON with UUID. It also discloses supported invoice types and customer-specific requirements, all 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 well-structured: a lead sentence, a 'Key facts' bullet list, a 'Returns' line, and an 'Args' section. It's moderately lengthy but every section serves a purpose given the tool's complexity, and it avoids repeating schema details verbatim.

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

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

With no output schema, the description explicitly states return values ('XML document string when not submitting, or JSON with UUID when submitting') and covers generation, submission, integration options, and plan requirements. Minor omissions like explicit error conditions do not significantly impact completeness for this complex tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds semantic constraints beyond the schema: e.g., 'For Private customers: sdi_type must be ''0000000'' and tax_id_code (codice fiscale) is required', 'For PA customers: use version=''FPA12'' and the 6-char PA office code as sdi_type', and VAT rates with nature code required at 0%. These enrich parameter understanding beyond the structured fields.

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

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

The description opens with 'Generate an Italian FatturaPA electronic invoice in XML format and optionally submit it to the SdI', which states a specific verb, resource, and scope. This distinguishes it from sibling tools like pop_create_ksef_invoice (Poland) or pop_create_zugferd_invoice (Germany) by explicitly targeting Italian FatturaPA e-invoicing.

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: Italian e-invoicing compliance (D.Lgs. 127/2015), support for B2B/B2C, customer types, and the Growth+ plan requirement for SdI submission. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of full exclusionary 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 indicate this is a write operation (readOnlyHint=false). The description adds that the API performs authoritative validation and returns generation metadata, which is useful context. However, openWorldHint=true is not addressed, and no side effects (e.g., external calls, persistence) are 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?

The description is two sentences with zero filler. It front-loads the main purpose and then adds a valuable note about validation. 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?

Given the complex nested schema and no output schema, the description is far too incomplete. It does not explain the return metadata structure, prerequisites, common use cases, or how the many fields interrelate. The sparse description leaves the agent to infer critical details from the schema alone.

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 coverage is only 40% and the description provides no parameter-level detail. It does not explain the required 'data' object, how to structure nested fields, or clarify any of the poorly documented parameters. The description adds no meaning beyond the schema's existing field 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 clearly states the tool generates a ZUGFeRD/Factur-X document package with specific components (visual PDF, EN16931 CII XML, hybrid PDF). This distinctly separates it from sibling tools like pop_create_sdi_invoice or pop_create_peppol_invoice.

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 ZUGFeRD/Factur-X invoices but gives no explicit guidance on when to choose this over alternatives, nor any exclusions or context about regional/regulatory applicability. It lacks a 'when to use vs. other tools' 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?

The description goes well beyond the annotations by explaining asynchronous processing, notification delivery, status meanings, and the need to wait and retry if no notifications are returned. This adds significant behavioral context that the annotations (readOnlyHint, idempotentHint, etc.) do not capture, making the tool's behavior predictable.

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 well-structured with a clear opening, a bulleted list of statuses, a note on retry, and an args section. Every sentence adds value, and the most important information is front-loaded. It is concise without being under-specified.

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 lack of an output schema, the description provides useful context by listing possible statuses and the meaning of response_format. It explains retry behavior and ties the uuid to pop_create_sdi_invoice. However, it does not describe the full response structure (e.g., fields beyond status/notifications) or error handling, leaving some ambiguity about the exact return format.

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 repeats the schema descriptions for uuid and response_format without adding new information, and it omits the environment parameter entirely. There is no added value beyond what the input schema already 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 opens with a specific verb and resource: 'Retrieve the SdI processing status and notifications for a submitted invoice.' It clearly identifies the tool's function and distinguishes it from sibling tools like pop_get_sdi_document (which retrieves the document itself) by focusing on status polling and notifications.

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 when to use the tool: 'After submitting an invoice to the Italian SdI... This tool polls the current status and all notifications.' It also advises on retry behavior. However, it does not explicitly name alternative tools or state when not to use it, which would earn a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds workflow context (processed document after submission), the checking of delivery status, and notes zone requirements for some regions, which goes 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?

The description is front-loaded with a clear purpose, split into a concise intro, usage context, and a short args list. It doesn't waste words, though the args list somewhat repeats schema 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?

Without an output schema, the description doesn't fully clarify what the tool returns—whether it's the document content, delivery status, or both. It hints at this via 'check its delivery status' and the response_format parameter, but a more explicit description of the return structure 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 coverage is 80%, and the schema documents most parameters. The description adds a valuable link for uuid (from pop_create_peppol_invoice) and hints at zone requirements, but these are also present in the schema. The response_format is only described as 'Output format,' adding minimal value.

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

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

The description opens with 'Retrieve a Peppol document from the network by UUID,' which clearly specifies the verb, resource, and key identifier. It distinguishes itself from sibling tools like pop_get_sdi_document by focusing specifically on the Peppol network.

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 'After a Peppol invoice is submitted, use this tool to retrieve the processed document or check its delivery status on the Peppol network,' providing a clear when-to-use context. However, it does not mention alternatives or exclusions, so it doesn't reach a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not repeat that. It adds valuable context beyond annotations, such as the storage location ('POP storage'), the document type (SdI/FatturaPA), and a critical requirement ('Growth+ plan with active SdI via POP integration'). This helps the agent understand prerequisites and trust boundaries.

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 well-structured and front-loaded with the primary action. It includes a use-case sentence, a requirement line, and a concise Args list. Every sentence earns its place, though the second sentence ('Fetches a previously submitted or preserved...') is somewhat redundant with the first and could be merged. Still, it is efficiently written overall.

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

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

With no output schema, the description should hint at what the response contains. It does this indirectly through response_format options ('readable summary' vs 'raw data'), which is helpful. However, it lacks information on the environment parameter, error cases, or what happens if the UUID is not found. Given the tool's simplicity and available annotations, the description is adequate but not exhaustive.

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 67% (uuid and response_format have descriptions; environment does not). The description adds meaning by explaining response_format values ('markdown' for readable summary, 'json' for raw data), but it omits the environment parameter entirely, leaving it undefined in both schema and description. uuid is adequately described in schema, so the description adds little there. Overall, the description partially compensates but leaves a gap.

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 primary action: 'Retrieve an SdI document from POP storage by UUID.' It uses a specific verb and resource, and distinguishes itself from sibling tools like pop_verify_sdi_document (verification) and pop_get_peppol_document (Peppol format) by focusing on SdI retrieval. The stated use cases (auditing, re-downloading, verifying stored invoices) further clarify its scope.

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: 'Useful for auditing, re-downloading, or verifying stored invoices' and specifies a prerequisite ('Growth+ plan with active SdI via POP integration'). It does not explicitly name alternatives or state when not to use the tool, which prevents a 5, but the context is sufficient for an agent to make a reasonable 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?

Despite annotations indicating read-only, open-world, idempotent, and non-destructive behavior, the description adds critical context: null values mean unsaved fields, locked fields must not be changed, capabilities determine integration options, and country labels are Italian. This goes beyond what annotations provide, enhancing transparency.

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 structured with a clear purpose statement, a sequence note, and a bulleted list of key behaviors. Every sentence and bullet adds value, no redundancy or fluff, making it appropriately sized for the tool's complexity.

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

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

With no output schema, the description thoroughly explains the return payload's structure and semantics (configurations, field_locks, capabilities, lookups, allowed_integration_toggles). It also tells the agent how to interpret and use the data, leaving no important context 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 input schema already fully describes the only parameter (onboarding_token) with its source and expiration. The description does not add additional meaning to the parameter, so the baseline score of 3 applies since schema coverage is 100%.

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 it retrieves the full account setup payload including current field values, lookup tables, capabilities, and integration state. It uses a specific verb and resource, and the phrase 'step 4 of 5 in the onboarding sequence' distinguishes it from related onboarding tools like pop_onboarding_get_status and pop_onboarding_save_account_setup.

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 'This is step 4 of 5 in the onboarding sequence' and 'Call this before save_account_setup', providing clear when-to-use guidance. It also lists what to understand from the response, making the intended usage obvious.

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?

Despite strong annotations (readOnly, idempotent), the description adds valuable behavioral context: auth_source meaning, step_visibility interpretation, and a clarification that certain integration_state values are expected and not errors. These prevent misinterpretation of response data.

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 well-structured with a clear opening, use-context, return list, exclusions, and key behaviours. Every section adds value and the formatting makes key facts scannable without unnecessary verbosity.

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 absence of an output schema, the description compensates by listing return attributes and explaining important response semantics. It also situates the tool within the 5-step onboarding flow and differentiates it from related tools, making it sufficiently complete for an 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 description coverage is 100%, including token provenance and expiry, so the description need not repeat parameter details. The tool description does not add much about the parameter itself, 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 clearly states the verb ('Retrieve') and resource ('current onboarding state'), and explicitly distinguishes itself from the sibling pop_onboarding_get_account_setup by noting it does NOT return configurations. The purpose is unambiguous and well-differentiated.

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

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

It provides explicit when-to-use context ('step 3 of 5', 'use to poll state or check progress') and names the alternative tool for configurations. This gives clear usage direction within the onboarding sequence.

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 goes far beyond annotations by disclosing key behaviors: OTP is returned directly in the response, expiry is 10 minutes, accounts are auto-created for new emails, administrators require a different password flow, and no API key is needed. This adds substantial context that annotations alone do not 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?

The description is moderately long but well-structured with a clear opening line and bullet points for key behaviors. Every sentence adds value, covering purpose, sequence, and edge cases. It is not overly verbose, though it could be slightly tightened without losing fidelity.

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 and lack of output schema, the description is remarkably complete. It covers authentication requirements (no API key), behavioral side effects (account creation), temporal constraints (10-minute expiry), and the exact next step in the workflow. This is sufficient for an agent to invoke the tool correctly and handle the response.

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 extra meaning by clarifying that 'lang' is only a session hint and does not affect response language, and that 'email' triggers automatic account creation if missing. This goes beyond the schema's field descriptions, justifying a 4.

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 purpose: 'Start the POP onboarding flow by sending a one-time password (OTP) to an email address.' It uses a specific verb and resource, and explicitly differentiates it from siblings by labeling it 'step 1 of 5' and referencing subsequent steps in the sequence.

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 by outlining the full onboarding sequence and specifically instructing to 'Pass it to pop_onboarding_verify_otp immediately.' It also notes edge cases (auto-creation, admin accounts) that affect when to use. However, it does not explicitly state when not to use this tool versus alternatives, so it falls 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?

Beyond the annotations (which only indicate non-read-only, non-idempotent, non-destructive), the description adds rich behavioral context: uniqueness requirement with 422 error, the meaning of sending 0 (stores null), the non-writing behavior after wizard completion (applied_changes=false), permanent locking of Peppol fields, and retry safety after SdI failure. This is value-added disclosure.

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

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

The description is front-loaded with the core purpose and uses clear bullet points for integration rules and key behaviors. It is longer than a simple two-sentence description, but this is justified by the tool's complexity. Minor inefficiency: the 'Key behaviours' list could be split further, but substance outweighs length.

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 has 18 nested sub-parameters and no output schema, yet the description covers the critical side effects (uniqueness, wizard completion guard, Peppol locking, SdI failure retry) and even hints at response fields (applied_changes, integration_state). It stops short of describing the full response structure or all error cases, but for a save action it is largely complete.

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

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

The input schema already provides 100% coverage for all parameters, so the baseline is 3. The description goes further by explaining the conditional logic between integration toggle fields (mutual exclusion, required peppol_* fields when active_peppol_integration=1) and the meaning of 0 for toggles, which is not evident from individual 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 opens with a specific verb+resource ('Save the account setup configuration') and clearly states its role as step 5 of 5 in the onboarding sequence. It distinguishes itself from sibling tools like pop_onboarding_get_account_setup by focusing on the write/update action.

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 integration rules (SdI vs Peppol, mutual exclusion, basic variant exclusion) and notes when it is safe/appropriate to call again (wizard incomplete, retry after SdI failure). It does not explicitly name alternative tools, but the step positioning and integration constraints implicitly guide selection away from read-only 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?

The description discloses many behavioral traits beyond the minimal annotations: the returned onboarding_token is 48 characters, token expires after 30 minutes, there is no refresh endpoint, token_issued_at/token_expires_at are ISO 8601, wizard_variant behavior depends on country setup, and no API key is required. The annotations only specify flags; the description enriches the agent's understanding of the tool's side effects, lifecycle, and response semantics.

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 well-structured and front-loaded: the first sentence states the core purpose, followed by sequence context, then bullet-point key behaviors. Each bullet is concise and information-dense, covering token, expiry, response fields, wizard variant, completion condition, and admin case. No wasted words; the length is justified by the tool's complexity.

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

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

With no output schema, the description fully compensates by explaining return values (onboarding_token, token_issued_at, token_expires_at, wizard_variant, wizard_required) and their significance. It also covers the token lifecycle, expiration handling, sequence context, and authentication nuance for admins. For a step in a multi-step onboarding flow, this is complete and actionable for an 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 description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema for parameters like otp (schema already notes 'or the administrator password for admin accounts'), email (schema already requires matching), and site_id/platform (schema already describes them). The description's value is more about return behavior than parameter semantics, so it stays at the baseline.

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 a clear, specific verb+resource: 'Verify the OTP from pop_onboarding_request_otp and obtain an onboarding token.' It explicitly references the sibling tool pop_onboarding_request_otp, distinguishing this as the verification step in the onboarding flow. The title and name are consistent, and the purpose 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 explicit usage context: 'This is step 2 of 5 in the onboarding sequence.' It states when not to continue ('If wizard_required is false after this step, the account is already fully set up. No further steps needed'), and offers an alternative when the token expires ('No refresh endpoint; restart from request-otp if expired'). It also notes when to use the admin password as OTP, giving clear when-to-use vs alternative 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 provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds context beyond annotations by explaining the legal preservation requirement and the status precondition. It does not explicitly state side effects (e.g., document becoming immutable), but given the annotations cover safety traits, the added context is sufficient.

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 well-structured: purpose, legal context, IMPORTANT usage rule, requirements, and args. It is slightly redundant ('Archive an SdI document...' and 'This tool archives a document...'), but each section serves a purpose and is front-loaded with the primary action.

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 no output schema, the description provides enough context to call it correctly: when to call, prerequisites, and the single key parameter. It does not describe return values, but the action is simple and the annotations fill in the rest. This is complete for a straightforward archival tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the uuid parameter but adds no extra meaning beyond the schema. The environment parameter is not mentioned in the description, but it is adequately described 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 opens with a specific verb and resource: 'Archive an SdI document in long-term digital storage.' This clearly distinguishes it from sibling tools like pop_get_sdi_document or pop_verify_sdi_document, which are read/check operations. The addition of 'conservazione sostitutiva' and the legal context further clarify scope.

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 states when to use: only after pop_get_invoice_status returns RC or MC, and explicitly lists statuses to avoid (NS, EC, SE, DT). Also gives a prerequisite (Basic+ plan with active SdI). This is model guidance with both inclusion and exclusion criteria.

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

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

Annotations show a non-read-only, non-idempotent, non-destructive operation; description adds that connector status is checked first and that the POP Cloud API performs authoritative payload validation/mapping. It does not disclose duplicate creation risks, failure behavior, or side effects beyond the Zoho connector, so only partial transparency.

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 purpose, and no filler. Every clause adds relevant context: connector status check, TD04 prerequisite, and authoritative validation/mapping by the POP Cloud API.

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, side-effecting sync tool with openWorldHint=true and no output schema, the description omits return values, error/duplicate behavior, and what happens on the Zoho side. The TD04 prerequisite and connector check are useful but insufficient for a mutation tool of this 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 description coverage is only 50%, and the description adds little beyond the schema. It repeats that connected_invoice_data is required for credit notes (already stated in the schema) and provides no guidance for undocumented top-level params like site_url, site_title, or plugin_version.

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?

Clearly states it synchronizes invoices or credit notes to the account's native Zoho Books/Invoice connector, with a specific verb and resource. The sibling tool names (pop_create_sdi_invoice, pop_create_ksef_invoice, etc.) make the Zoho-specific target distinct.

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?

Implies usage for Zoho syncing and provides a prerequisite for TD04 credit notes (reference in connected_invoice_data), plus the default connector-status check. However, it does not explicitly say when to use this tool over alternatives or when not 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 indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by explaining the validation checks performed, the requirement for a 'Basic+ plan with active SdI via POP integration and registered business,' and the fact that it does not submit. This enriches behavioral transparency 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?

The description is well-structured and front-loaded with the main purpose, followed by usage context, a bulleted list of checks, and requirements. The 'Args' section is somewhat redundant with the schema, slightly impacting conciseness, but the overall organization makes 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?

The description covers the essential aspects: purpose, usage timing, prerequisites, and validation checks. It lacks an output schema, so a note about the return value or error reporting would be helpful, but the description gives sufficient context for a pre-submission validation tool.

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

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

Schema coverage is 100%, with both parameters including descriptions. The description's 'Args' section repeats the exact xml_base64 schema description without adding further meaning, and it omits the environment parameter entirely. The schema already fully defines the parameters, so the description adds no new semantic 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 states the tool's action: 'Validate an SdI (FatturaPA) XML document for compliance before submission.' It uses a specific verb and resource, and explicitly contrasts with submission by saying 'without actually submitting it,' distinguishing it from sibling tools like pop_create_sdi_invoice.

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: 'Use this tool to check if an SdI XML document passes XML syntax validation and Italian e-invoicing compliance checks — without actually submitting it.' It frames the tool as a pre-submission validation step to catch errors. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.

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