Well

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

Beyond the annotations (readOnlyHint false, destructiveHint false), the description discloses concrete behavioral details: E.164 normalization with a leading '+' added, default label 'work', default platform 'website', and a clear error for unsupported phone/company combinations. It also mentions wrapping REST endpoints and shows the channel-to-value mapping.

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 one-line summary, endpoint reference, channel mapping table, and a note section. Every sentence carries useful information; there is no repetition of schema content or fluff, despite 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?

Given the complexity (nested value objects, multiple channel types, unsupported combinations), the description covers all necessary context: endpoint wrapping, field mappings, defaults, and exceptions. The presence of an output schema means return-value documentation is unnecessary, and the description sufficiently covers the remaining behavioral context.

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?

Although the input schema covers 100% of parameters with descriptions, the description adds essential cross-parameter logic: how 'channel' selects which 'value' sub-fields to populate (email → value.email, phone → value.e164_number, etc.). This mapping is not evident from the flat schema and is critical for correct invocation.

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: 'Add a contact channel to a company or person.' This clearly states both the action and the target, and it naturally distinguishes from sibling tools like well_remove_contact_channel and well_query_records.

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 when to use an alternative: 'To READ existing channels, use well_query_records on the parent (companies/people) or the channel root.' It also warns against unsupported combinations (phone on company), preventing misuse.

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), the description discloses concrete behavioral details: enrichment runs asynchronously, the company is available immediately, enriched fields may take a few seconds, and the user should re-query after a delay. It also specifies the exact success/failure return format. This is rich, honest 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 efficiently organized: a one-sentence purpose, an explicit usage trigger, required/optional fields, a note on async enrichment, and the return format. Every sentence delivers value—no filler or redundancy.

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

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

For a create tool with an output schema, the description covers all essential context: purpose, when to use, parameter expectations, async side effects, and return structure. The workspace_id and idempotency_key are already fully documented in the schema, so the description does not need to repeat them. It is complete for the tool's 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?

The input schema already provides descriptions for all four parameters (100% coverage). The description adds little beyond restating that 'name' is required and 'description' is optional—information already present in the schema. It does not explain workspace_id or idempotency_key behavior, which the schema already covers. Baseline 3 applies.

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

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

The description clearly states 'Create a new company in the current workspace'—a specific verb and resource. It distinguishes itself from sibling tools like well_update_company and well_delete_company by focusing solely on creation, and the trigger phrasing 'create, add, or register a new company' reinforces its unique role.

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

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

The description explicitly instructs when to use the tool: 'Use this tool when the user asks to create, add, or register a new company.' This provides clear context, though it does not explicitly mention alternatives (e.g., well_update_company for updates), 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 only indicate non-read-only and non-destructive. The description discloses crucial behaviors: it never overwrites a real ingested document, creates and attaches a PDF, returns signed URLs with expiration, and does not email. This goes well beyond annotations, covering edge cases and side effects.

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 long but every sentence adds value: core action, logo edge case, usage timing, non-goals, prerequisite, refusal, return structure, URL semantics. It is well-sectioned and front-loaded, making it easy to scan. No filler or redundancy.

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

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

The description fully covers the tool's purpose, prerequisites, constraints, return values, and link behaviors. Even with an output schema present, it explains what the file object contains and which URL to give the user. It is complete for both 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 descriptions cover workspace_id and idempotency_key, and the description adds critical semantics for invoice_id ('the invoice must already exist') which is not in the schema. However, the description does not elaborate further on workspace_id or idempotency_key, relying on schema text. Since schema coverage is 67% (not >80% but not low), the additional invoice_id context pushes it to 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 opens with a specific verb+resource: 'Render an existing invoice as a print-ready PDF and attach it as the invoice's source document.' This clearly distinguishes it from siblings like well_create_invoice_from_data (which creates a new invoice) and well_update_invoice (which updates fields). It also explicitly states what it does NOT do (email/send), preventing misuse.

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 guidance: 'Use this tool when the user asks to generate, render, or attach a PDF for an invoice that already exists in the workspace.' It also gives a required prerequisite (invoice_id must exist), a refusal condition (already linked to a real ingested document), and what the tool does not do. This is exemplary usage guidance.

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

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

With only minimal annotations (readOnlyHint=false, destructiveHint=false), the description carries the full burden and does so thoroughly. It discloses persistence behavior, the risk of company re-resolution causing wrong attachments or duplicates, and the double-write confirmation problem when combined with update calls. These are behavioral traits beyond what annotations convey.

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

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

The description is long but every sentence is purposeful. It opens with the core purpose, moves to a clear field list, and closes with a decisive 'ONE CALL IS THE WHOLE WRITE' callout. The structure uses paragraphs, bullets, and bolded hints to guide the reader, with no filler or redundancy.

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

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

For a complex tool with 12 parameters, nested objects, and significant operational pitfalls, the description covers the entire workflow: when to use, what fields to fill, how to avoid duplicates, and how to set status. The output schema exists, so not detailing return values is acceptable. It also references sibling tools for company lookup, making it contextually complete.

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

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

Schema coverage is 50%, so the description compensates by providing a structured field map for issuer/receiver, totals, line_items, and payment_means. It adds crucial semantics like 'company_id ALWAYS send this when you already know the company' and explains status derivation. While some details are already in the schema, the description enriches meaning, especially for nested objects lacking individual 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 creates an invoice from structured data extracted via OCR, explicitly distinguishing it from file upload ('you send the structured fields, not the file'). The verb 'create', the resource 'invoice', and the source 'data you extracted' are all specific and differentiate it from sibling tools like well_create_invoice_document and well_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 explicit when-to-use guidance: use when you have structured data from OCR, and explicitly warns against pairing with well_update_invoice ('Creating and then patching the same invoice writes twice'). It also explains when to pass status and company_id, referencing well_query_records and well_get_entity for finding companies, and names the alternative of simply uploading a document.

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

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

With annotations already indicating this is a write operation (readOnlyHint=false) and not destructive, the description adds valuable context: 'After creation, enrichment runs asynchronously in the background' and the exact success/failure return shape. This goes beyond the annotations and helps the agent anticipate side effects and response format. It does not, however, detail what 'enrichment' entails or potential failure modes, so it is not a full behavioral disclosure.

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

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

The description is tightly written with a clear structure: purpose, usage guidance, required/optional summary, async behavior, and return format. Every sentence earns its place, and the most important information is front-loaded. It is neither verbose nor ambiguous.

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 create tool with good schema coverage and an output schema, the description covers all essential aspects: what it does, when to use it, required/optional fields, background enrichment, and return values. The workspace_id and idempotency_key nuances are handled by the schema descriptions, so the description itself is complete for the agent to select and 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?

The schema already provides descriptions for 5 of 7 parameters (71% coverage). The description adds a concise summary of REQUIRED first_name and OPTIONAL last_name/job_title, but it omits email and phone which are also optional and lack schema descriptions. Since the description does not fully compensate for the missing email/phone semantics, it adds moderate value but falls short of fully clarifying all parameters.

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 'Create a new person (contact) in the current workspace,' which uses a specific verb and resource while clarifying the scope. It further distinguishes from sibling tools like well_create_company by explicitly covering 'add, create, or register a new contact, employee, or person.' This makes the tool's 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 states when to use the tool: 'Use this tool when the user asks to add, create, or register a new contact, employee, or person.' It also mentions the current workspace context and that enrichment runs asynchronously. However, it does not explicitly state when not to use it or mention alternatives (e.g., well_update_person for updates), so it stops short of a full when/when-not/alternatives explanation.

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 beyond the destructiveHint annotation by explaining that the delete is a soft delete, that company_person relationships are removed, that linked people records are NOT deleted, and that invoices/documents referencing the company are preserved. It also discloses the return format, providing rich behavioral context beyond the annotations.

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

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

The description is compact and well-structured: it starts with the core purpose, then usage guidance, then side effects, and finally the return contract. Every sentence contributes useful information without redundancy, and the formatting 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?

Given the tool's simplicity, the description is complete: it explains what is deleted, what is preserved, and what the return value looks like. Even with an output schema present, it provides a concise summary of success/failure behavior, and the schema covers parameter 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?

The input schema already provides 100% coverage of all parameters (company_id, workspace_id, idempotency_key) with clear descriptions. The main description only reiterates that company_id is required without adding additional semantics, so it adds minimal value beyond the schema.

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

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

The description clearly states 'Delete a company from the current workspace (soft delete)' with a specific verb and resource. It distinguishes from sibling deletion tools by specifying that only the company is soft-deleted while linked people records and invoices/documents are preserved, making the tool's scope 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 says 'Use this tool when the user asks to delete, remove, or archive a company,' providing clear when-to-use guidance. However, it does not explicitly name alternative tools for deleting other entities (e.g., well_delete_person, well_delete_invoice), so it falls short of the full when-not/alternatives clarity seen in top-tier examples.

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 annotation destructiveHint=true, the description adds significant behavioral detail: it is a soft delete, linked line items and payment_means rows remain orphaned, and reversal is only possible at the database level. This is critical context for an agent deciding whether to use the tool.

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

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

The description is concise and well-structured: a one-line summary, a clear 'REQUIRED' note, and bullet-like consequences of the delete. It is easily scannable and every sentence contributes meaningful 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?

For a destructive operation, the description explains the full impact: what will be deleted (invoice), what will NOT be deleted (line items, payment_means), and the reversibility limitation. Combined with the rich schema annotations, this is complete enough for an agent to safely invoke the 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?

The input schema provides 100% coverage with descriptions for all three parameters. The description only restates that invoice_id is required, adding no new information about workspace_id or idempotency_key. Thus the added value over the schema is minimal, matching the baseline for full 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 explicitly states the action: 'Delete an invoice from Well (soft delete).' It uses a clear verb+resource structure and distinguishes itself from sibling delete tools (e.g., well_delete_company, well_delete_person) by targeting invoices specifically.

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 by explaining this is a soft delete and warns about the non-cascade behavior for linked rows. However, it does not explicitly mention when to use this tool over alternatives or state exclusions, so it falls short of fully explicit usage 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 mark destructiveHint=true, but the description adds significant behavior: soft delete, cascading company_person relationships, linked companies NOT deleted, and the restriction that a user cannot delete their own record. It also documents the exact return shape, going far beyond annotation 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?

Description is well-structured and dense: a one-line summary, a clear usage trigger, a required parameter note, key behavioral caveats, and return format. Each sentence contributes unique value 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?

The tool has a straightforward action with one required parameter, and the description covers all key aspects: what happens (soft delete), scope (current workspace), side effects (relationship removal), exclusions (companies, own record), and the success/error response. The output schema exists, so further return detail is unnecessary.

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?

Input schema descriptions cover 100% of parameters, so the baseline is 3. The description only repeats that person_id is required and does not add extra semantic detail beyond the schema's built-in explanations. No additional parameter context is provided.

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

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

Description clearly identifies the tool as deleting a person/contact with 'soft delete' semantics, distinguishing it from sibling delete tools like well_delete_company and well_delete_invoice. The verb 'delete' and resource 'person' are specific and unambiguous.

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

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

Explicitly states when to use: 'when the user asks to delete, remove, or archive a contact.' Provides clear context but does not offer exclusions or name alternative tools for related scenarios, so it lacks the full when-not guidance for 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 significant behavioral context beyond the readOnlyHint=true annotation: it explains the `unavailable` and `partial` flags with concrete examples, clarifies this is a snapshot only, and defines the FX as_of anchor date. This is exactly the kind of nuance that prevents misinterpreting placeholder values as real balances.

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 in five focused paragraphs, each serving a distinct purpose: definition, return values, edge-case flags, forward-looking disclaimer, and entry prerequisite. Despite being lengthy, there is no filler; every sentence adds necessary information for correct invocation.

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

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

The description fully covers the tool's unique edge cases (`unavailable`, `partial`, FX rate anchor), distinguishes from runway, and states the token-based workspace resolution. With a rich output schema and annotations, this description leaves no critical gap for an agent trying to use 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?

The sole parameter workspace_id has 100% schema description coverage, including the omit behavior. The description reinforces that workspace resolution comes from the caller's authorized token and that no other call is needed, but it doesn't add syntax or format details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get the workspace's current cash position: total cash on hand right now, converted to the workspace base currency, plus a per-account breakdown.' It also explicitly differentiates from manual summing and later from well_get_runway, making the tool's purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use this instead of summing account balances yourself' and contrasts with the alternative 'Call well_get_runway instead for a forward-looking figure.' It also states a prerequisite: 'Call this directly — no other tool call is needed first,' covering both usage and exclusions.

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

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

Beyond the readOnlyHint annotation, the description discloses detailed behavior: return shape (entries, currency, rung, hints), the meaning of each rung, that amount is a magnitude not signed, and the requirement to disclose hints. It also explains that workspace is resolved from the authorized token, which adds useful context.

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

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

The description is longer than the calibration ideal but well-structured with clear sections: purpose, return details, rung explanation, hints, and call convention. Every sentence carries relevant information, though some redundancy exists with the schema description for workspace resolution.

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 an output schema exists, the description need not explain return values, yet it does so thoroughly. It covers purpose, usage, behavioral edge cases (rung fallback), and hints disclosure, providing a complete picture for correct invocation and result interpretation.

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 a detailed workspace_id description already in the input schema. The tool description adds minimal new parameter meaning; it only reaffirms that workspace is resolved automatically, which is already implied by the schema's 'Omit to use the only authorized workspace' language.

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

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

The description clearly states a specific verb+resource+scope: 'Get the workspace's cost structure: outflow for the latest closed month, broken down by category.' It explicitly differentiates from manual transaction summing/grouping and references the exact same computation as the Well app's donut chart, making it unique among sibling tools.

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

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

The description tells the agent when to use this tool ('Use this instead of summing/grouping transactions yourself') and that no prerequisite call is needed ('Call this directly — no other tool call is needed first'). It does not explicitly name sibling alternatives or exclusion cases, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds critical behaviors beyond that: 'Stops at depth 3. Aggregates are excluded. Each child collection is capped at 50 rows.' This gives the agent concrete expectations about limits and exclusions.

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 one-sentence summary, followed by a comparison to alternatives, then depth-level details, and finally limitations with a pointer to the alternative tool. Every sentence adds 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 an output schema present, return values are already specified. The description fills in operational context: depth semantics, sub-resource examples, row caps, aggregate exclusion, and when to use an alternative. This makes the tool fully self-explanatory 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 coverage is 100%, so the baseline is 3, but the description significantly enhances understanding of the 'depth' parameter by explaining what each level (1, 2, 3) returns and noting the payload size impact. Other parameters are already well-documented in the schema, so the extra depth semantics justify a score above baseline but not a 5 since not all parameters receive additional context.

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 'Read ONE entity with its sub-resources nested in a single call,' using a specific verb and resource while clearly defining the tool's scope. It also distinguishes itself from sibling tools by naming well_get_schema and well_query_records as alternatives.

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 this tool: 'Convenience over well_get_schema + well_query_records' and provides an alternative for other cases: 'use well_query_records on that child root instead.' Depth-level guidance further clarifies usage boundaries.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds valuable context beyond that: data is fetched fresh from Plaid on every call, never stale, and only works for Plaid connectors supporting the investments product. 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?

Well-structured with a clear opening summary, numbered workflow, and explicit exclusions. Each section earns its place; no fluff or redundancy.

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

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

Despite having an output schema, the description provides necessary context about prerequisites, connector eligibility, and alternative paths for transactions. It is complete for a tool with this complexity and connector ecosystem.

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 descriptions for both params. The description adds extra meaning for workspace_connector_id by showing exactly where to obtain it (from well_list_connectors row), which is beyond the schema's basic description.

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 retrieves live holdings/positions for connected Plaid investment accounts, with specific account types (brokerage, IRA, 401k). It distinguishes itself from sibling tools by explicitly excluding transactions and passthrough tool usage.

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 a step-by-step workflow: first call well_list_connectors, pick the enabled Plaid connector, then call this tool with the workspace_connector_id. It also explicitly states when not to use it (not for MCP-transport passthrough tools, not for transactions) and points to well_query_records as the alternative.

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 readOnlyHint annotation by explaining status discriminator semantics (ok, capped, infinite, insufficient_data), partial=true behavior, and the exclusion-count/hints handling. It gives a complete behavioral picture without contradicting 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 detailed but every sentence is purposeful, with a clear first-sentence summary, bulleted status patterns, and a final usage note. It is front-loaded and structured for quick comprehension without fluff.

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?

Even though an output schema is present, the description adds essential context: status meanings, capped/infinite handling, partial-data caveats, and the no-prerequisite instruction. It fully equips the agent to interpret results and act on edge cases.

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 already provides 100% coverage for workspace_id, including omission behavior. The description's note that workspace is resolved from the caller's token adds minimal value beyond what the schema states, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns the workspace's cash runway with specific metrics (cash on hand, trailing-3-month burn, months left) and explicitly ties it to Well app KPI cards, differentiating it from raw data reads and sibling tools like well_get_cash_position.

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 instructs to use this instead of computing runway from raw account/transaction reads, states no other tool call is needed first, and points to well_list_connectors as an alternative when data is insufficient. This is strong when/when-not 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses the return format (path, type, context, enrichment), provides examples of operator compatibility by type, and explains the meaning of 'context' and 'enrichment'. It also includes the path-to-array conversion detail for downstream use. This is rich behavioral context that goes far 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 structured with clear sections (USAGE, WORKFLOW, return format explanation). Every sentence provides necessary information for the agent to use the tool effectively. While it is longer than typical descriptions, the length is justified by the tool's role as a schema discovery gateway, and the 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 fully covers what the tool does, how to invoke it, what it returns, how to interpret the results, and how to integrate with well_query_records. Given the tool's purpose and the presence of an output schema, the description explains the semantic meaning of returned fields and operator selection, making the context 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%, so the schema already documents all parameters. The description adds value by showing example calls, clarifying the meaning of omitting root, and explaining how the returned field metadata (type, context) relates to filter operators in well_query_records. It does not elaborate on depth or workspace_id, but those are well-described in the schema, so the extra context still justifies a score above 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 clearly states the tool discovers available data types and fields. It provides specific usage examples (e.g., 'well_get_schema()' to list all roots, 'well_get_schema({ root: "invoices" })' to list fields) and distinguishes itself from sibling tools like well_query_records by explaining it is the discovery step before querying.

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

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

The description gives explicit workflow steps: call well_get_schema first, pick 5-15 fields, then call well_query_records. It also specifies when to omit the root argument (list all roots) and how to use the returned type information to construct whereClause operators. This is clear, actionable guidance with no ambiguity about when 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?

The description adds valuable context beyond the annotations, such as eligibility ('Only works on connectors that expose an MCP server... and whose connection is enabled'), return format ('Returns the provider's tool result, or { success: false, error }'), and authorization context ('on behalf of this workspace's connection'). 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 somewhat long but well-structured: a clear opening statement, an exclusion note, and a numbered workflow. Each part serves a purpose, and the list format aids comprehension. No wasted words, though it could be tightened slightly.

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 (5 params, nested args, output schema, annotations), the description covers all necessary context: prerequisites, discovery process (workflow), usage restrictions, and error behavior. It is comprehensive without needing to explain return values since an output schema exists.

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

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

Schema coverage is 100%, so baseline is 3. The description adds workflow-level meaning: workspace_connector_id comes from well_list_connectors, tool must be 'one of the names from step 2', and args are 'passed straight to the provider tool'. This enriches parameter understanding beyond the 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 clearly states the tool's function: 'Run one tool on a connected provider's own MCP server' with a concrete example ('create a record in Attio'). It distinguishes itself from siblings by explicitly contrasting with well_query_records for reading financial data and by outlining a workflow that separate steps.

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 when-to-use and when-not-to-use guidance: 'Use this ONLY for an action the user explicitly asked to take on that provider' and 'It is NOT a way to read financial data... read those with well_query_records instead.' It also names the alternative tools in the workflow.

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

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

Annotations only declare readOnlyHint=true and destructiveHint=false, but the description adds extensive behavioral context: install_url behavior ('works from any state — it signs the user in if needed...'), connection_status state meanings, the instruction to resolve workspace_connector_id here rather than via well_query_records, and the default vs q-search behavior. This goes well beyond what annotations convey.

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

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

The description is lengthy but structured: starting with purpose, then field-by-field bullets, then usage distinctions. Every sentence adds value, though a few statements are repeated (e.g., the 'This is ALSO' point appears twice). It is front-loaded and organized, earning a 4 rather than a 5.

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 (many response fields, connection states, and install links), the description is remarkably complete. It explains each response field, how to interpret status/connection_status, when to pass q, and how to use install_url. The existing output schema would further support return values, but the description already covers the crucial context.

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 covers all 4 parameters with descriptions (100% coverage). The description reinforces the q parameter's role ('pass q to name-search the full catalog') and default/limit behavior, but does not add meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'List the connectors a workspace can install, each with a one-click install deep link.' It clearly distinguishes this from sibling tools by stating it answers 'what can I connect to Well?' and explicitly directing users to well_list_connector_tools for live connection actions.

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

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

The description gives explicit when-to-use guidance: 'Use this to answer...' and 'This is ALSO the tool that answers...' It names alternatives (well_list_connector_tools, well_query_records) and states 'Use well_list_connector_tools for a live connection's actions.' This satisfies exclusions and alternatives.

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 destructiveHint false, and the description does not contradict them. It adds valuable behavioral detail about the reconnect_url field and the 'need_reconnect' status, explaining that a stale/revoked token results in no tools being returned and directing the user to re-authenticate, which is beyond the annotation 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 long but well-structured with a numbered workflow and a clear purpose front-loaded. The reconnect_url instructions are necessary for error handling and earn their place, though the example parenthetical adds a bit of extra length. Overall, the structure is effective and every section serves a purpose, so not quite a 5.

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 an output schema present and the description covering the full discovery workflow, input sourcing from a prior tool, and the reconnection failure mode, the tool is thoroughly contextualized. An agent has all necessary information to select and invoke this tool correctly, including how to handle error responses via reconnect_url.

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 covers both parameters (workspace_id and workspace_connector_id) with descriptions, achieving 100% coverage. The description reinforces that workspace_connector_id comes from well_list_connectors, but this is also in the schema, so no new semantic meaning is added beyond what the schema provides. Baseline 3 applies.

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

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

The description clearly states the tool lists actions a connected provider exposes, using the verb 'Discover' and an example ('what can I do with Attio?'). It distinguishes itself from sibling tools by outlining the broader workflow (list_connectors → list_connector_tools → invoke_connector_tool), making its specific role as the discovery step 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 an explicit numbered workflow and instructs to use this tool 'whenever you don't already know a connector's tool names — never guess them.' It also names the alternatives (well_list_connectors for the ID, well_invoke_connector_tool for invocation) and specifies the reconnect_url handling for failure cases, giving comprehensive when-to-use and when-not-to-use 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 mark the tool as read-only and non-destructive, and the description adds detailed behavioral context: it explains each output field, null handling when accounting settings are absent, exclusion of tax identifiers, and the semantics of is_primary. This exceeds what annotations alone offer.

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-organized with a clear opening statement, a bulleted list of output fields, and a concise behavioral note. Every sentence contributes necessary information without redundancy, making it appropriately sized for the content.

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

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

Despite having only one optional parameter, the tool's output structure and cross-tool behavior are fully explained. The description covers return fields, edge cases, and integration with other tools, making it complete 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?

The input schema already describes workspace_id thoroughly (100% coverage), so the description doesn't need to repeat it. However, it enhances understanding by explaining how the returned workspace_id is used in other tools and clarifies omission semantics (single vs. multiple workspaces), adding value beyond the schema.

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

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

The description clearly states the tool 'List the workspaces this connection is authorized to access', using a specific verb and resource. It distinguishes itself from sibling tools by focusing on workspace enumeration, and the title matches the purpose.

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 instructs 'Use this FIRST when a single token may cover more than one workspace.' Provides detailed guidance on when to omit or supply workspace_id across read and write tools, and explains fan-out behavior for multiple workspaces. This goes beyond vague alternatives to give concrete usage rules.

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?

Even with readOnlyHint=true already declared, the description adds rich behavioral context: 'fields is ADDITIVE — it widens the data you receive, never the table the user sees,' pagination guidance ('nextCursor' is NOT a to-do), aggregate-vs-paginate rules, and the return envelope { rows, totalCount, nextCursor, success }. It fully discloses the read-only nature, the additive field semantics, and the one-call-is-the-answer philosophy, going far 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 long but tightly organized with clear headers (WORKFLOW, ROOTS, CONNECTED TOOLS, RULES, FILTERING, SORTING) and concise examples. Each section earns its place, providing actionable guidance without fluff. The structure makes dense information scannable for an agent.

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 is exceptionally complete for a complex query tool: it covers workflow, root enumeration, filtering operators and syntax, sorting, pagination rules, output shape, and integration with sibling tools. With a high-parameter schema and output schema present, the description complements rather than repeats, leaving no major operational gap.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: fields are 'EXTRA field paths... additive only,' with detailed explanation of display-view behavior and composite types. It clarifies allFields is not preferred, documents default/max limits, distinguishes safe vs. type-specific filter operators, and explains workspace_id semantics. This is far beyond 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 clearly states 'Query records from Well's database' and enumerates all 33 read-only roots, making the scope explicit. It distinguishes itself from siblings by explicitly steering agents away from well_list_connectors and provider connector tools for data retrieval. The 'CONNECTED TOOLS' section reinforces its unique role as the primary record-reader.

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 when-to-use vs. alternatives: 'do NOT use this tool to show the user what they have connected — call well_list_connectors instead' and 'well_invoke_connector_tool... never a way to fetch data Well already holds.' It also instructs calling well_get_schema(root) first for targeted field discovery, and gives concrete workflow examples for two common use cases.

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 destructiveHint=true, so the destructive nature is known. The description adds valuable behavior beyond annotations: it specifies that channel_id must be the channel row's UUID, explicitly warns 'NOT the parent', and references the DELETE endpoints. This helps prevent misuse.

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 sentences, no fluff. The purpose, endpoint, and key caveat are front-loaded and every sentence earns its place. It is compact yet highly informative.

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

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

The description covers the operation's purpose, endpoint, required parameter distinction, and how to obtain the necessary ID. With output schema present and annotations covering destructiveness, the tool is well-rounded for the task. It does not explain error behavior but that is not essential here.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by emphasizing the distinction between channel_id and parent_id, and by advising how to find the correct channel_id via well_query_records. This extra clarification is valuable.

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 first sentence clearly defines the action: 'Remove a contact channel from a company or person.' This is a specific verb + resource, and the sibling context (well_add_contact_channel) makes the inverse operation obvious. The description also names the underlying delete endpoints, reinforcing the purpose.

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 use: it targets contact channels not parent records, and instructs how to locate the channel_id via well_query_records. It does not explicitly mention alternative tools or when-not-to-use, but the prerequisite and scope are clearly implied.

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 readOnlyHint=false and destructiveHint=false, so the tool is a write operation but not destructive. The description adds important behavioral details: each task resolves independently, failures do not block the batch, and idempotency via key. These go beyond what annotations provide, though the exact reversibility could be clearer.

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

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

The description is concise and well-structured: a lead sentence stating purpose, followed by bullet-style action explanations and additional batch behavior. Every sentence adds value, and the most critical information is front-loaded.

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 complexity (batch, idempotency, workspace authorization) and the presence of an output schema, the description covers all essential aspects: purpose, actions, error handling, and parameter roles. No gaps remain for an agent to effectively use the 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 75% with descriptions for workspace_id and idempotency_key. The description adds meaning to action (approve/reject effects) and explains that task_ids resolve independently, supplementing the schema's minimal description. This adds value beyond the schema.

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

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

The description clearly states that the tool approves or rejects reconciliation review tasks, specifies the source (well_run_register_diff or in-app queue), and explains the effects of each action. It distinguishes itself from similar sibling tools like well_resolve_register_diff_gap, which resolves gaps not tasks.

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

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

The description implies when to use the tool (to approve/reject reconciliation tasks) but does not explicitly state when not to use it or provide alternatives. The context is sufficient for a basic understanding, but lacks explicit guidance on selecting this tool over others.

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 behavioral traits beyond annotations: it is a write operation (not read-only), fails with errors rather than silently no-oping, and requires prerequisites. Annotations indicate readOnlyHint=false, which is consistent, and the description adds context about failure modes and data integrity.

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

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

The description is concise (4-5 sentences) and front-loaded with the core purpose. Every sentence adds necessary guidance without redundancy. The structure efficiently conveys purpose, prerequisites, and error conditions.

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 (5 parameters, write operation, output schema present), the description is complete. It covers all important aspects: purpose, parameter details, prerequisites, error behavior, and retrieval guidance. The presence of an output schema reduces the need to describe return values.

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 adds significant meaning beyond the input schema: it clarifies that bank_ledger_account_id is the bank/cash account and category_ledger_account_id is the expense/income category. It also explains that task_id refers to a gap review task. With 100% schema coverage, the description still adds value by contextualizing the parameters.

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: 'Post a well_run_register_diff gap ... into QuickBooks as a Purchase or Deposit.' It uses a specific verb ('Post') and resource ('gap'), and distinguishes it from sibling tools like well_resolve_reconciliation_task by referencing 'register diff gap'.

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 guidelines: requires exact ledger_account_ids obtained via well_query_records, warns against guessing or fuzzy matching, and specifies conditions that cause failure. This tells the agent when and how to use the tool safely.

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 fully discloses behavioral traits: persisting results, creating review tasks, handling matches, gaps, contended, and unexplained entries. It clarifies that nothing links automatically and requires human decisions via sibling tools. This goes well beyond annotations (readOnlyHint=false, destructiveHint=false) to provide detailed behavioral expectations.

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

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

The description is concise yet comprehensive, using bullet points to organize different scenarios. Every sentence adds value without redundancy. It is front-loaded with the main purpose and then details specific behaviors efficiently.

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 (5 parameters, output schema exists), the description covers all key aspects: what happens to matches, gaps, contended, and unexplained entries, how to resolve them, and edge cases like feature disabled. The presence of an output schema reduces the need to describe return values, and the description is complete.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds minimal context beyond the schema (e.g., mentioning QuickBooks as an example for the register connector). It does not elaborate on parameter usage or format further, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool diffs bank transactions against accounting-register transactions and persists the result. It specifies the verb 'diff', the resources, and the outcome, and distinguishes from sibling tools like well_resolve_reconciliation_task and well_resolve_register_diff_gap.

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 explains when to use the tool (for reconciling bank and register transactions) and references sibling tools for subsequent steps. It also notes that if the feature is off, the tool returns enabled: false with all counts 0. However, it does not explicitly state when not to use this tool, such as when only partial matching is needed or when no persistence is desired.

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 destructiveHint=true, and the description adds valuable context: the NOT CHANGEABLE field list, the instruction to only include fields the user wants changed, and the return shape on success/failure. It does not contradict annotations.

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

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

The description is well-structured with clear sections (REQUIRED, OPTIONAL, NOT CHANGEABLE, RETURNS) and is front-loaded with the core purpose. Every sentence provides necessary operational or restrictive information without unnecessary fluff.

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 15-parameter write tool, the description covers the primary usage context, field restrictions, and return behavior. The output schema and annotations fill most remaining gaps. However, it omits mention of the workspace_id requirement when multiple workspaces are authorized, which is an important edge case left to the schema description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds group-level semantics: REQUIRED vs OPTIONAL, the 'only include fields the user wants changed' rule, and format clarifications for locale and registry_country, which go beyond the 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 clearly states the tool updates an existing company, with specific verb and resource. It distinguishes from siblings by explicitly noting fields that are NOT changeable and emphasizing 'existing' company, which separates it from well_create_company and well_delete_company.

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 explicit usage guidance: 'Use this tool when the user asks to change, fix, rename, or edit a company's fields.' It also lists what cannot be changed and notes dedicated tools for those cases, though it does not name specific sibling tools as alternatives.

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 destructive (destructiveHint=true), so the bar is lower. Description adds valuable context: partial-update semantics ('only pass fields you want changed'), null-to-clear behavior, and explicit unsupported fields. 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-sentence lead with a clean bullet list. Each line earns its place: purpose, a required prerequisite, parameter grouping, and an explicit exclusion. No filler, front-loaded with the 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 19-parameter tool with output schema, the description covers core update semantics, required parameter, optional fields, and exclusions. Directs to well_get_schema for full field discovery. However, it omits some important nuances like payment_status requiring override_version (CAS) and workspace_id rules for multi-workspace tokens, leaving the schema to carry that burden.

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 baseline is 3. Description adds a grouped summary of optional fields and crucially clarifies 'null to clear, omit to leave unchanged' semantics, which is present in schema but reinforced here. It also excludes line items/payment_means/attachments, clarifying parameter boundaries. However, it omits mention of payment_status/override_version pairing and workspace_id requirement, which schema covers.

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 'Update an existing invoice in Well' with a specific verb and resource. Clearly differentiates from sibling tools like well_create_invoice_from_data and well_delete_invoice. Also notes limitations ('Cannot change line items, payment_means, or document attachment'), further clarifying 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?

Explicitly instructs to call well_get_schema("invoices") for field discovery, and states what cannot be changed (line items, payment_means, attachments), guiding when not to use this tool. However, it doesn't name alternative tools for those excluded operations, missing a stronger when-not-to-use signal.

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 destructiveHint=true and readOnlyHint=false, and the description aligns with that. It adds valuable context beyond annotations: it clarifies partial-update semantics ('only include fields the user wants changed'), lists fields that cannot be updated, and specifies the return format on success and failure. This exceeds the baseline, though it doesn't cover authorization or idempotency, which the schema handles.

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

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

The description is concise and well-structured. It front-loads the core purpose, then uses labeled sections (REQUIRED, OPTIONAL, NOT CHANGEABLE, Returns) to organize information. Every sentence contributes value; there is no redundancy or filler.

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

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

For a tool with 6 parameters, the description covers the key person fields and explicitly notes what is not changeable. While it doesn't mention workspace_id or idempotency_key, those are adequately described in the schema and are common across tools. The return format is specified, and the output schema exists. Overall, it is complete enough for an agent to use confidently, with minor gaps around workspace authorization and idempotency.

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 meaningful semantic context: it identifies person_id as required, lists the optional editable fields, and emphasizes that only included fields should be changed. This reinforces the partial-update behavior and prevents the agent from sending unchanged fields. It also clarifies that job_title can be null to clear, matching the schema.

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

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

The description clearly states the tool's purpose: 'Update an existing person (contact) in the current workspace.' The verb 'update' plus resource 'person' is specific and distinguishes it from siblings like create_person and delete_person. It also enumerates the exact use case: 'change, fix, rename, or edit a person's fields.'

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: 'Use this tool when the user asks to change, fix, rename, or edit a person's fields.' It also provides clear exclusions: 'NOT CHANGEABLE via this tool: emails, phones, locations, linked companies, media. Those require dedicated tools (not yet available).' This tells the agent what not to use it for and acknowledges alternatives.

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