Invompt

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

Annotations already indicate destructiveHint=true, but the description adds that this is a 'soft delete' and that 'historical invoice snapshots and links remain stable', which is valuable context beyond the raw annotation. It does not contradict annotations; in fact, it clarifies the nature of the destructive action.

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-loads the key action and condition (explicit confirmation), and uses concise language. Every word serves a purpose without redundancy.

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

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

For a destructive operation with an output schema (present) and full schema coverage, the description covers the essential behavior: when to use (after confirmation) and what happens (soft delete). Minor gaps like potential side effects on linked invoices are addressed by 'links remain stable', so 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 schema has 100% coverage for parameters, so the description does not need to repeat parameter details. It adds a slight nuance by implying that 'confirmed' is used for explicit confirmation, but that is already in the schema. Thus, it meets the baseline for high schema coverage without adding significant new meaning.

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 (archive) and the resource (saved client), and adds the crucial qualifier that it is a 'soft delete' with stable historical data. This distinguishes it from a hard delete, though it doesn't explicitly differentiate from archive_invoice, but the resource is clear.

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 states that it should be used only after explicit confirmation, and that it is a soft delete, which implies a non-destructive context. It doesn't mention alternatives like update_client for reversible changes, but the confirmation requirement is a clear usage condition.

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

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

Annotations already mark this as non-read-only, non-destructive, and idempotent. The description adds valuable layer: the invoice remains viewable and financial documents are never permanently deleted, which prevents an agent from fearing data loss. This supplements the annotation profile usefully.

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

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

A single sentence that defines scope, action, and consequences with zero fluff. The key constraints are front-loaded ('Archive, remove from active lists, or soft-delete') followed by the essential caveat.

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 that an output schema exists and annotations cover the mutation safety profile, this description is sufficient. It doesn't state preconditions like 'invoice must exist', but that's largely inferable and the focus on soft-delete plus non-destructive semantics covers the main agent concern.

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

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

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description adds no extra param-level meaning, but that's acceptable because the schema carries the load; baseline 3 is appropriate here.

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

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

The description uses specific verbs ('Archive, remove from active lists, or soft-delete'), identifies the target resource ('a clearly identified invoice'), and names the ownership constraint ('owned by the connected workspace'). This distinguishes it from siblings like unarchive_invoice and create_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 the tool is for invoices that should no longer appear in active lists and clarifies that financial documents are never permanently deleted. While it doesn't explicitly contrast with unarchive_invoice, the context is clear enough for an agent to choose appropriately.

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

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

The description provides substantial behavioral detail beyond the annotations: the link is short-lived, sensitive, expires, must be presented once, and must not be logged. It also notes transport-neutrality and that the backend decides eligibility, which helps the agent anticipate failure modes and handling 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 compact and front-loaded: the first sentence gives the main action and purpose, the second adds eligibility constraints, and the third notes security handling. Every sentence contributes necessary information with no 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?

With zero parameters and an output schema present, the description covers all essential context: what the tool does, who can use it, how the link behaves, and important security constraints. Nothing critical is missing for an agent to 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 input schema has zero parameters and full schema description coverage, so the baseline is 4. The description adds no parameter-level detail, but none is needed because there are no parameters; the relevant constraints are contextual, not argument-based.

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

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

The description names a specific verb ('create'), a specific resource ('short-lived browser link'), and the exact purpose: letting the current Guest claim a workspace into an authenticated account. It clearly differentiates this from sibling tools by focusing on workspace claim via a Guest session rather than, say, invoice link renewal.

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 the tool is Guest-account-only, giving a strong condition for when it should be used. It does not explicitly name alternative tools for non-Guest users, but the intended context is unambiguous and the backend eligibility check is disclosed.

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

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

Annotations already mark this as non-read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: it is an explicit user-approved save, not a background side effect, and duplicate candidates must be confirmed. This is relevant behavioral disclosure without contradicting the annotations.

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

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

Two sentences pack the core action, the user-consent condition, the sibling-tool exclusion, and the duplicate policy without fluff. The most important behavioral constraint is front-loaded in the first sentence.

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

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

For a mutation tool with annotations, an output schema, and an 11-parameter schema, the description covers the critical invocation and duplicate conditions. It does not explain the optional customer fields or outcomes, but those are either self-explanatory or covered by the output schema, making it complete enough for correct selection and invocation.

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

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

Schema description coverage is only 18%, so the tool description needed to carry more parameter guidance, but it only meaningfully covers allowDuplicate (and references the duplicate flow). The other optional fields are left entirely to their names and schema constraints, so the description falls short of compensating for the low coverage.

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

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

The description states a specific verb and resource: explicitly save a reusable client. It is distinguished from create_invoice by forbidding silent calls, and the title reinforces the create-client purpose. This clearly separates it from sibling client tools like get_client, list_clients, and update_client.

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 an explicit invocation condition (after the user chose save and assign), a prohibition (never call silently from create_invoice), and a duplicate-handling policy (require confirmation before retrying with allowDuplicate=true). This tells the agent exactly when and when not to use the tool.

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

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

Goes well beyond the annotations by disclosing strict rejection of unsupported fields, the requirement for idempotencyKey, the rule to never invent issuer identity, the no-silent-client-save policy, and the clientId snapshot behavior. These are important behavioral traits not visible from the readOnly, openWorld, idempotent, or destructive hints.

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 information-dense and front-loaded, but it is presented as one long, stream-of-consciousness paragraph with repetition, such as 'never silently save' appearing twice, and a punctuation typo. Structured bullets or shorter sentences would improve scannability.

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, the rich schema, the output schema, and the annotations, the description is remarkably complete. It covers input-form selection, required fields, rejected fields, safety rules around clients and issuer identity, idempotency, and even directs the agent to the InvoML spec for full fidelity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real cross-parameter meaning: exactly one of document or invoml must be provided, which fields are rejected, when legacy invoml is needed, and what clientId does. This meaningfully supplements the schema without replacing it.

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

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

States a specific verb, resource, and scope: creates and hosts an Invompt invoice, quote, estimate, or pro forma. It clearly distinguishes the two supported input forms and differentiates the strict document form from the legacy invoml form, so an agent can tell what the tool is for without ambiguity.

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

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

Provides strong workflow guidance: search list_clients first, auto-select only an exact unique match, ask on multiple or no matches, and never silently save a client. It also directs users to invoml for full fidelity versus the strict document form, though it does not explicitly compare against update_invoice or archive_invoice.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds meaningful behavioral context by disclosing that private notes and Web-specific rich HTML are never exposed, and that the result is the canonical structured billing-party subset. This goes beyond the structured annotations without contradicting 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?

Two short sentences: the first front-loads the core action and scope, the second adds an important transparency guarantee. Every word earns its place; there is no repetition of schema or annotation data.

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

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

For a simple single-parameter read with a full output schema and annotations covering safety, the description is complete. It covers what is returned, what is intentionally not returned, and the scope ('company-owned'). No critical behavioral or usage context is missing.

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

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

Schema description coverage is 100%, and the id parameter is already described as 'Company-owned saved client ID'. The tool description adds no additional parameter-level detail beyond reinforcing that the client is company-owned, which is already in the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Get') and resource ('client'), and narrows scope to 'canonical structured billing-party fields' for 'one company-owned saved client'. It clearly distinguishes itself from list_clients and update_client by emphasizing a single, read-only, canonical representation.

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 a single saved client's canonical billing fields, but it does not explicitly mention when to use this over list_clients or when not to use it. The note about private notes and rich HTML being never exposed suggests limitations, but no alternative tools or explicit exclusions are named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the entire InvoML content is returned and that the invoice is scoped to the connected workspace, which supplements the annotations without contradicting 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 two sentences, front-loaded with the primary verb and resource. The enumeration 'Get, retrieve, open, or inspect' is slightly redundant, but otherwise every clause carries useful information.

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

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

With one well-documented parameter, a full output schema, and annotations covering the safety profile, the description conveys the core intent and the intended downstream uses of the return value. It does not need to detail return fields or errors.

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

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

Schema description coverage is 100% (the only parameter, id, is described as 'Invoice ID'). The description adds no parameter-specific detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('Get') and a precise resource ('one invoice owned by the connected workspace') and highlights the key content ('full InvoML content'). It clearly differentiates from siblings like list_invoices and get_invoice_template.

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 explains why the returned InvoML is useful ('for revisions, translations, duplication, or as a template'), giving clear context for when the result is needed. It does not explicitly name alternatives or exclusion conditions, but the single-invoice scope is unambiguous.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, so the description need not repeat that. It adds genuinely useful behavior beyond the annotations: the preset is 'immutable' and 'validated,' and the rendered HTML/CSS is intentionally empty in v1, which prevents an agent from expecting populated markup. 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, with the primary action front-loaded and the v1 caveat in a short second sentence. There is no filler or redundant restatement of the tool name. The dense phrase 'selected immutable, validated semantic preset' is the only minor clarity cost, but overall the description is efficient.

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 annotations, fully documented parameters, and existing output schema, the description covers the important non-obvious facts: single-workspace ownership, immutable/validated preset, and empty rendered HTML in v1. It would be slightly better if it pointed to list_invoice_templates as the enumeration sibling, but nothing needed to call the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents templateId and version. The description adds little parameter-level meaning beyond the 'workspace-owned' scope and the existence of the preset; the schema already explains the version default and the company-owned template ID.

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

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

The description uses a specific verb ('Retrieve'), identifies the resource ('one workspace-owned invoice template'), and names the companion payload ('selected immutable, validated semantic preset'). The singular 'one' distinguishes it from list_invoice_templates, the template focus separates it from get_invoice, and the v1 HTML/CSS caveat clarifies what this tool returns versus a rendered-template tool.

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

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

The description implies use when a single template plus its preset is needed, and the 'workspace-owned' and 'intentionally empty' phrasing adds context. However, it never explicitly names alternatives such as list_invoice_templates or get_invoice, nor does it state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by specifying the exact data returned (saved invoice defaults) and the scope (connected workspace), and notes that some fields are optional. It does not contradict annotations and provides useful context beyond the hints.

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, efficiently front-loaded with the core action ('Get saved invoice defaults') followed by a concise list of included fields. There is no redundancy or filler; every word contributes to clarity.

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 parameters and an output schema exists, the description is complete for an agent to call it correctly. It states what the tool retrieves and its scope. No additional information is needed for invocation; the output schema handles return structure.

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

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

The tool has zero parameters, and schema coverage is 100% (trivially). Per the baseline for 0 params, a score of 4 is appropriate. The description does not need to explain parameters, as there are none, and it correctly focuses on the output fields instead.

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: retrieving saved invoice defaults for the connected workspace. It lists specific fields (company name, currency, invoice prefix, numbering format, default due date, sender info, payment terms), making it unambiguous and distinct from sibling tools like get_client or get_invoice. The verb 'Get' and resource 'settings' are precise.

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 context ('for the connected workspace') but does not explicitly state when to use this tool versus alternatives. It implies it is for retrieving defaults, likely before invoice creation, but does not name update_settings or other get tools as alternatives, nor does it exclude scenarios. There is no explicit when-to-use 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?

The annotations already communicate read-only, idempotent, and non-destructive behavior. The description adds genuinely useful behavioral detail: only exact_unique matches are auto-selected, ambiguous results require user choice, and no-match results trigger a user prompt about saving/assigning versus one-off data. 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?

The description is compact and front-loaded with the core action and workflow context. Each sentence adds behavioral guidance. The only minor issue is the dense internal phrase 'resolution.kind=exact_unique', which may not be self-explanatory but is still 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?

The core search-and-resolve workflow is well covered, and an output schema exists so return values need not be described. However, the description omits the list-all behavior implied by the optional page/limit parameters and the tool title, leaving the listing use case under-specified.

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

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

Schema description coverage is only 33%, so the description needed to compensate for the undocumented page and limit parameters, but it does not. It restates 'name or email' for search, which the schema already provides, and provides no added semantics for pagination limits or defaults.

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 ('Search saved clients by name or email') and ties it to a concrete workflow ('before creating an invoice for a named recipient'). This clearly differentiates it from sibling tools like get_client (ID lookup) and list_invoices, and matches the title's list/search framing.

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

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

It gives clear, actionable context for when to call the tool: before creating an invoice with a named recipient. It also prescribes how to behave on ambiguous matches and on no matches. It does not explicitly name alternatives or state when not to use the tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns only summaries (not full content), lists the exact summary fields, and scopes results to the connected workspace, which informs agent expectations about output and limitations.

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, purpose is front-loaded, and the pointer to get_invoice is efficient. However, the opening synonym string 'Find, browse, show, search, or list' is somewhat redundant, preventing a perfect score for conciseness.

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 presence of an output schema and 100% parameter schema coverage, the description provides enough context for correct tool selection and invocation: purpose, workspace scope, return summary fields, and a clear alternative for full content. The minor omission of pagination defaults is already handled by the schema, so nothing critical is missing.

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

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

The schema has 100% description coverage, with each of the four parameters (page, limit, search, status) described. The tool description does not add any parameter-specific meaning beyond the schema, so it sits at the baseline for this dimension.

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 invoices owned by the connected workspace, using explicit verbs like 'find', 'browse', 'search', and 'list'. It distinguishes itself from the sibling get_invoice by noting that get_invoice provides full InvoML content, making the purpose unambiguous.

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

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

The description explicitly tells the agent to use get_invoice when full InvoML content is needed, providing a clear when-not and alternative. It also implies general browsing/searching use cases through its verbs and mention of search and status filtering, giving sufficient guidance for most scenarios.

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, so the safety profile is covered. The description adds useful behavior beyond those annotations: it promises only safe metadata, emphasizes the active/reusable filter, and scopes results to the connected workspace.

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

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

Two tight sentences with no filler. The core action and scope are front-loaded, and the pointer to the alternative tool is placed at the end without disrupting the main purpose.

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

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

For a simple list tool with strong annotations, an output schema, and fully documented optional parameters, the description is sufficient. It also anticipates the likely follow-up need by directing the agent to get_invoice_template for deeper semantics.

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 fully documents both parameters, including the status const and the documentType enum. The description does not need to repeat parameter details; the baseline 3 applies because it adds no extra semantic value over the schema for parameter usage.

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 ('List') and a precise resource ('active reusable invoice templates available in the connected workspace'). It also explicitly contrasts this listing tool with get_invoice_template, so an agent can distinguish it from the closest sibling without opening the schema.

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

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

It clearly states the scope ('active reusable templates') and the safe-metadata-only nature of the result, then names the alternative tool for the richer semantic preset. This gives the agent an explicit routing rule: use this for safe metadata, use get_invoice_template for the full validated preset.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the specific detail that workspace status is included, which is a modest enhancement beyond a pure connectivity check but does not go into behaviors like response format or latency.

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 that delivers the core purpose in an efficient, front-loaded manner. No words are wasted.

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

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

For a zero-parameter health check with an output schema present, the description is complete. The agent knows exactly what the tool does and does not need additional details about return values because the output 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics because the input schema is empty and there is nothing to document.

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

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

The description uses a specific verb 'check' and identifies two concrete targets: API connectivity and the connected workspace status. This clearly differentiates it from all sibling tools, which focus on clients, invoices, templates, and settings.

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 is used to verify connectivity and workspace status, but it does not explicitly state when to prefer it over alternatives or what conditions prompt its use. There are no direct alternatives for a ping operation, so the implied usage is acceptable but not fully 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 already declare readOnlyHint=true and idempotentHint=true, and the description adds value by enumerating excluded data (recipient identity, payment data, generated values, free-form content, rendered HTML/CSS) and the opt-in requirement for line items. This goes beyond the annotation safety profile, though it does not describe the output structure.

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

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

Two sentences, front-loaded with the purpose and followed by concise exclusion details. No filler or redundant wording.

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 output schema and annotations, the description covers core behavior and exclusions. It leaves the exact meaning of 'semantic template projection' slightly vague, but the included exclusions and opt-in rule are sufficient for safe invocation.

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

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

Schema description coverage is 100%, so each parameter already has a clear description. The description's mention that 'line items require explicit opt-in' restates the includeLineItems default/false semantics without adding new meaning 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 uses the specific verb 'Preview' and names the resource 'safe semantic template projection from an immutable invoice revision.' It lists exclusions, which distinguishes it from sibling get_invoice_template that would return the full template.

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

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

The word 'Preview' and 'safe' imply it is meant for non-destructive inspection before acting, but the description never names an alternative tool or states when not to use it. Usage must be inferred from context.

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

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

Annotations already declare destructive, non-read-only, idempotent, and open-world behavior. The description adds valuable specifics beyond annotations: the replacement link is 72-hour, and the previous public link is revoked only when the connected service supports renewal. This gives agents useful side-effect awareness while some edge cases remain unstated.

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 front-loaded sentences with no filler. The first states the primary action and its boundary, and the second states the key side effect. 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 two-parameter tool with a full output schema and annotations covering safety, the description is largely complete. It covers purpose, key side effect, and the external dependency on service support. It does not elaborate on the fallback behavior when renewal is unsupported, but the core call guidance is 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%, so the schema fully documents id and idempotencyKey. The description reinforces that the invoice is existing, but does not add meaningful parameter semantics beyond the schema; the baseline of 3 applies.

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

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

The description states a specific verb and resource: issuing a replacement 72-hour hosted review link for an existing invoice. It explicitly distinguishes the action from creating or revising the invoice, which separates it clearly from siblings like create_invoice and update_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 gives clear context: use this for an existing invoice when a new hosted review link is needed, and clarifies it does not create or revise the invoice. It does not explicitly name sibling alternatives or provide a when-not-to-use list, so it stops short of full alternative routing.

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

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

The description adds meaningful behavior beyond the annotations: the server recomputes projectionChecksum and rejects host-supplied HTML, CSS, assets, and arbitrary defaults. This helps the agent understand what will be validated and what inputs are ignored, complementing the idempotentHint and readOnlyHint=false 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 only two sentences and front-loads the main purpose. It is dense and uses some jargon like 'semantic projection', but every clause carries information and there is no filler.

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

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

Given the output schema, annotations, and 100% parameter documentation, the description covers the key context: safe projection, server-side checksum recomputation, and the rejection of custom host inputs. It does not explain the exact template creation behavior, but the overall context is sufficient for an agent to invoke the 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 each parameter is already documented with descriptions. The description adds value by clarifying that projectionChecksum is recomputed server-side and that host-supplied content is not accepted, but it does not systematically explain individual parameter usage 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 identifies the action (save) and the resource (an immutable invoice revision as a reusable workspace template), making the tool's purpose evident. It distinguishes itself from preview_invoice_template_extraction by emphasizing 'confirmed safe' and 'reusable workspace template', though it does not explicitly name a sibling.

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 workflow: only a confirmed safe projection should be saved, and the server recomputes the checksum. However, it does not explicitly state when to use this tool versus preview_invoice_template_extraction or other template-related tools, leaving prerequisites and exclusions mostly implicit.

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

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

The annotations already establish that this mutates state and is idempotent. The description adds useful behavioral context beyond that: the email contains a server-rendered PDF attachment, and the operation has an account prerequisite with a specific Guest onboarding path. 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 compact and front-loaded with the core action, then quickly covers prerequisites, exclusions, and pre-call steps. Every sentence earns its place without redundant filler.

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

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

For a mutating email-sending tool, the description covers the core action, account prerequisite, guest fallback, exclusions, and required pre-call verification. Combined with the rich 100%-covered schema and output schema, nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the individual parameter meanings are already fully documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, which matches the baseline for high 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 opens with a specific verb and resource: 'Send an existing invoice as a server-rendered PDF attachment by email.' It clearly delineates what the tool does and distinguishes itself from sibling tools by explicitly saying it is not for creating, editing, or downloading an 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?

Usage conditions are explicit: a registered account is required, Guest connections must use create_account_claim_link first, and the user should identify the invoice via get_invoice/list_invoices and confirm the recipient before calling. This provides both when-to-use and when-not-to-use 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 the operation is mutating, idempotent, and non-destructive. The description adds useful behavioral context beyond that: the invoice reappears in active lists, content is preserved, and only invoices owned by the connected company are eligible. 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?

A single sentence that front-loads the core action, then states the result and the key constraint. Every clause earns its place with 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 output schema, full parameter coverage, and annotations, the description is nearly complete for a straightforward mutation. It could have explicitly mentioned the version-concurrency requirement or pointed to archive_invoice, but the schema descriptions already cover those details.

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

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

Schema description coverage is 100%, and each parameter (id, idempotencyKey, expectedVersion) already has a meaningful schema description. The tool description adds no additional parameter-level detail, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Restore') and resource ('archived invoice') and clearly states the outcome: the invoice returns to active lists. It also notes that document content is unchanged, distinguishing it from related operations like archive_invoice without ambiguity.

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: the tool is for restoring an archived invoice, and it adds the ownership constraint ('owned by the connected guest company'). It does not explicitly name alternatives or say when not to use it, but the sibling set and the verb make the intended use 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?

Beyond annotations, which already flag mutation, idempotency, and destructiveness, the description discloses optimistic concurrency protection, retry safety, and a concrete side-effect guarantee that invoice recipient snapshots never change automatically. This is valuable behavioral context not derivable from the schema or 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 short sentences, front-loaded with the action and key guarantees. Every clause earns its place with no filler or repetition.

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

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

For a 12-parameter mutation tool, the critical non-obvious semantics are covered: version guarding, idempotent retries, and non-cascading snapshot behavior. The output schema and annotations carry the remaining load, though optional-field semantics and explicit sibling routing are not addressed.

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 25%, leaving nine optional fields mostly undocumented, and the description does not compensate by explaining them. It does map 'optimistic version protection' and 'retry safety' to expectedVersion and idempotencyKey, but the meaning of fields such as attention or businessNumber remains unclear.

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 verb 'Partially update' plus the resource 'saved client' precisely identifies a PATCH-style mutation and clearly distinguishes it from create/get/list siblings such as create_client and get_client. Adding 'optimistic version protection and retry safety' further clarifies the operation mode.

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 is for modifying an existing saved client, but it never explicitly states when to prefer it over create_client or how to route between update_client and update_invoice. There is no when-not-to-use guidance or alternative naming, so an agent must infer applicability from the wording 'saved client'.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the bar is lower. The description still adds meaningful behavioral context: null clientId 'detaches the link but keeps the current recipient snapshot', a UUID 'rebuilds this invoice snapshot' (disclosing destructive overwrite), and the no-auto-rewrite rule for historical invoices. There is 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?

Three dense sentences, each earning its place: the action scope, the clientId decision table, and the historical-invoice immutability warning. The synonym chain 'update, revise, correct, translate, restyle' is slightly redundant, but each maps to a real capability (numberCorrection, invoml, templateId), so it is justifiable rather than padding.

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

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

For a 7-parameter mutation with nested objects, the description covers the genuinely tricky semantics (client link states, snapshot rebuild, number immutability) while the output schema and 100%-coverage input schema handle return values and remaining parameters. Authentication scope ('owned by the connected workspace') is noted. Minor gaps like resync failure behavior are not critical given the schema richness.

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 schema already documents clientId's omit/null/UUID semantics nearly verbatim, and numberCorrection's 'from must equal current canonical number' rule. The description adds modest extra meaning around the resync workflow (why a snapshot rebuild matters, historical immutability), but the schema carries most of the parameter burden.

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

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

The description names a specific resource ('an existing invoice owned by the connected workspace') and a concrete action set (update, revise, correct, translate, restyle, resync). It differentiates from siblings implicitly: update_client handles the client resource itself, create_invoice handles new invoices, and the 'existing invoice owned by the connected workspace' scoping sets it apart from archive/send tools. The synonym cluster is slightly broad, but the resource and scope are unambiguous.

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

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

The description gives clear context for when to use this tool: correcting persisted numbers, translating, restyling via template, and explicitly resyncing a client. The clientId omitted/null/UUID trichotomy is a precise usage rule, and 'Client edits never rewrite historical invoices automatically' signals when an explicit resync is required. It stops short of naming when-not-to-use alternatives (e.g., create_invoice for new invoices), so it earns a 4 rather than 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?

The description adds meaningful behavior beyond the annotations: PATCH semantics ('omitted fields remain unchanged'), null-clearing for companyName and currency, and the return of the complete canonical settings. Annotations already indicate destructive and idempotent behavior, so the description need not repeat them. 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?

Three dense sentences with no filler. The action and scope are front-loaded, and the null-clearing and return behavior are stated efficiently. 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?

The description covers the core mutation semantics, null behavior, and return value, and the output schema handles return structure details. It does not clarify the semantics of less obvious properties like paymentInfo or senderInfo, but the schema plus self-explanatory names make the definition still work well. Overall, it is complete enough for an agent to invoke 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?

With schema description coverage at only 13%, the description carries extra weight for parameter meaning. It usefully explains null-clearing for two parameters and the general omit-to-keep behavior, but it does not explain senderInfo, paymentInfo, invoicePrefix, defaultDueDate, or invoiceNumberFormat beyond their names. The idempotencyKey description in the schema partially compensates.

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

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

The description names a specific verb and resource: 'partially update saved invoice defaults for the connected workspace.' It clearly distinguishes this from sibling tools like update_invoice and update_client by scoping it to workspace-level defaults. The terminology is precise enough that an agent can confidently select it.

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

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

The description clearly signals when to use the tool: when modifying saved invoice defaults at the workspace level. It does not explicitly name alternatives such as get_settings or update_invoice, but the resource scope is unambiguous enough to route selection. It lacks explicit exclusions, so it stops short of a 5.

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