Well

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

Beyond the annotations, it discloses the underlying POST endpoints, the E.164 normalization ('a leading + is added if missing'), optional defaults for label and platform, and the unsupported company+phone case. This significantly helps an agent predict behavior before calling.

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

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

The description is front-loaded with the core action, then uses compact bullet mappings and a final note for edge cases. Every line carries operational value; nothing is redundant.

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 nested-object, multi-enum creation tool, it covers all critical input semantics, the invalid phone/company case, and routing to the read tool. The output schema exists, so return-value detail is not required. The definition is complete enough to call 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 channel-to-value mapping is explicit and goes well beyond the schema: email→value.email, phone→value.e164_number, web_link→value.url, location→value.city/country. It also clarifies optional fields and defaults. Schema coverage is 100%, but the description adds the crucial combination semantics.

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

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

The description opens with a specific verb and resource: 'Add a contact channel to a company or person.' This goes beyond the title, defines the operation precisely, and is distinct from siblings 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?

It gives an explicit alternative for reading channels ('use well_query_records on the parent'), and it warns against an invalid combination: phone on company returns a clear error. This is concrete 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?

The description goes beyond the annotations by disclosing that enrichment runs asynchronously, that the company is available immediately, and that enriched fields may take a few seconds to appear. This is practical behavioral context an agent needs to manage user expectations and decide to re-query later.

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

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

The description is well-structured and front-loaded: purpose, trigger conditions, parameters, asynchronous behavior, and return value each have a clear place. Every sentence earns its keep with no 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?

The description covers the action, when to use it, required vs. optional parameters, post-creation async behavior, and the success/failure return shape. With rich schema descriptions and annotations also present, nothing essential is missing for an agent to call this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds a useful REQUIRED/OPTIONAL summary and mentions the current workspace, but it does not meaningfully explain workspace_id or idempotency_key beyond what the schema already provides.

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

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

The description clearly states the action as 'Create a new company in the current workspace' and reinforces it with 'when the user asks to create, add, or register a new company.' This distinctly differentiates it from sibling tools like well_create_person or well_create_invoice_from_data.

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

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

The description explicitly says when to use this tool: when the user asks to create, add, or register a new company. It names the required and optional parameters but does not explicitly contrast this with updating an existing company via well_update_company, though the 'new company' phrasing largely makes that clear.

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

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

Annotations only say readOnlyHint=false, leaving write behavior undisclosed. The description fills this gap thoroughly: it attaches the PDF, never overwrites a real ingested source document, explains the logo fallback, and details refusal conditions. It also clarifies return behavior and link expiry.

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 average but every section earns its place: core action, subtle logo behavior, usage condition, refusal condition, and return details with link semantics. It is scannable and front-loaded with the main verb and resource.

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 with an output schema present, the description usefully explains the return contract including file links and expiration semantics. It covers preconditions, refusal cases, logo caveats, and non-email scope, making the tool callable without further investigation.

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

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

Schema coverage is 67%, and the description adds meaningful semantics for invoice_id by marking it required and requiring the invoice to already exist. workspace_id and idempotency_key are already well-described in the schema, so the description doesn't need to repeat them, though it doesn't tie them into the tool flow.

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 ('Render an existing invoice as a print-ready PDF and attach it as the invoice's source document') plus a concrete resource. Clearly distinguishes this from sibling tools like well_create_invoice_from_data and well_update_invoice by anchoring on an already-existing 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?

Explicitly says when to use it: when the user asks to generate, render, or attach a PDF for an invoice already in the workspace. It also states what it does not do (does not email or send) and when it is refused, though it does not name an alternative tool to use when the invoice does not yet exist.

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 (readOnlyHint=false, destructiveHint=false), the description discloses important side effects: re-resolving a party without company_id 'can attach the invoice to the wrong company or create a duplicate one,' and creating then patching 'writes twice and shows the user two confirmations for one action.' This goes far beyond the annotation metadata.

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 efficiently organized: the core distinction is front-loaded, the field summary is compact, and the critical workflow warning is isolated under a bolded heading. A small amount of redundancy exists with the schema's own company_id description, but no sentence is 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 12-parameter, nested-object write tool, the description covers the full data shape, formats, the workflow around status and company_id, and the pitfalls of double-writing. An output schema exists, so return-value explanation is unnecessary, and the combination leaves no significant gap for an agent to call this tool correctly.

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

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

Schema coverage is 50%, and the description compensates with a compact field map including formats (YYYY-MM-DD, ISO 4217) and nested structures (issuer/receiver, totals, line_items, payment_means, status). It adds decision-level semantics—e.g., 'ALWAYS send this when you already know the company' for company_id and 'pass status:"draft" here' for status—meaning beyond the raw 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 states a specific verb and resource: 'Create an invoice in Well from data you extracted by reading an invoice' and distinguishes itself by clarifying 'you send the structured fields, not the file.' It also frames itself as the complete write, contrasting with well_update_invoice, which makes its role clear relative to siblings.

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 tells when to use this tool instead of alternatives: don't use well_create_invoice_document when you have structured fields rather than a file, and don't follow up with well_update_invoice because 'ONE CALL IS THE WHOLE WRITE.' It also gives concrete conditions like passing status:'draft' when the user asked for a draft and passing company_id when the company was already found via well_query_records or well_get_entity.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the description adds valuable context beyond those: it discloses that enrichment runs asynchronously after creation, that required vs optional fields are listed, and it shows the exact success/failure return shape. This gives the agent important knowledge about side effects and response behavior that annotations alone do not 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?

Four short, focused sections: what it does, when to use it, required/optional fields, and return behavior. The most important trigger phrase is front-loaded, and every sentence earns its place 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?

The tool has an output schema, so return values are already documented structurally. The description covers the creation workflow, async enrichment side effect, required fields, and error behavior. Given the moderate complexity (7 params, 1 required, no nested objects), this 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 coverage is 71%, and several parameters already have descriptions (job_title, last_name, first_name, workspace_id, idempotency_key). The description reinforces required/optional semantics for first_name, last_name, and job_title. It does not explain email or phone in prose, but the schema already describes them adequately, so the marginal gap is small.

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 and resource ('Create a new person (contact)') and gives concrete synonyms ('add, create, or register a new contact, employee, or person'). Clearly distinguishes from siblings like well_create_company and well_create_invoice_document, while the emphasis on 'person' and 'current workspace' differentiates it from well_update_person and well_delete_person.

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 says when to use this tool ('when the user asks to add, create, or register a new contact, employee, or person'). It also clearly signals alternatives by naming sibling tools that create other entity types or update/delete people, so an agent can route correctly.

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?

Discloses one-time token burn, 15-minute expiry, single-workspace authorization, pre-allocated document_id, 'not_found_yet' semantics before upload, and the card auto-refresh behavior that eliminates the need for polling. This far exceeds what the annotations convey and materially affects how an agent should invoke and follow up.

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 multi-paragraph but every block earns its place: purpose, usage conditions, lifecycle constraints, and preallocation semantics. Some repetition around polling and card rendering exists, but it is not padded overall.

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

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

Covers the full lifecycle: mint URL/token, POST raw bytes, call result exactly once, card rendering behavior, expiry and burn, and pre-upload result semantics. Given that an output schema is present, nothing needed for correct use 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?

Input schema coverage is 100%, so the baseline is 3. The description reinforces that workspace_id may be omitted when the token authorizes one workspace, but it does not add significant parameter-level meaning beyond the schema's existing 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?

States a specific verb ('Mint') and resource ('one-time, short-lived upload slot for a bank-statement file'), which clearly distinguishes it from the many sibling create_* tools and from well_get_statement_import_result. The title alone is generic, but the description anchors the tool precisely.

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 says to use this when the user has a statement file (PDF, large CSV/XML) to import and notes that the file bytes do not travel through the model. It also prescribes the follow-up call to well_get_statement_import_result once, but it does not name an alternative tool or explicitly 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?

The annotations already signal destructiveHint=true, but the description goes further by explaining that it is a soft delete, what gets deleted, what is preserved, and the success/failure response shape. This is exactly the side-effect context an agent needs.

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: purpose first, then trigger phrase, required parameter, side effects, and return contract. Every sentence earns its place 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 destructive tool with three parameters and an output schema, the description plus the schema fully cover what the deletion affects, what is preserved, the required ID, and the expected result. Nothing important 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 input schema already provides 100% description coverage, including rich explanations for company_id, workspace_id, and idempotency_key. The description only repeats that company_id is required and does not add much semantic value 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: Delete a company from the current workspace, and immediately qualifies it as a soft delete. This distinguishes it clearly from sibling delete tools such as well_delete_invoice and well_delete_person.

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

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

It explicitly states when to use the tool: when the user asks to delete, remove, or archive a company. It does not mention alternatives or exclusions, so it stops short of full 5-level 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 description explicitly reveals the soft-delete behavior, the lack of cascade deletion for line items and payment_means rows, the orphaning effect, and that reversal is only possible at the database level. These are material side effects that go beyond the destructiveHint annotation and should influence an agent's decision to call 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 core operation and critical caveats are front-loaded and written densel y, with no filler. The redundant 'REQUIRED: invoice_id' line repeats schema info, which keeps it from being perfectly lean.

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 contains everything an agent needs to decide whether to call and whatto expect: soft delete, orphaned rows, database-only reversibility, and required argument. The output schema covers return values and the input schema covers workspace/dempotency details, so no critical 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?

The input schema already documents all three parameters, including workspace_id's conditional requirement and idempotency_key behavior, so the description adds no new parameter semantics. Its only param note, 'REQUIRED: invoice_id', duplicates the schema's required field.

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 ('Delete an invoice from Well') and immediately qualifies it as a soft delete. This clearly distinguishes it from update/company/person siblings, so an agent knows exactly what action is offered.

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 states what the operation does but does not explicitly say when to prefer it over alternatives, nor does it name sibling tools as alternatives or exclusions. Usage must be inferred from the verb 'delete', which is a reasonable but implicit 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?

The annotations only indicate destructiveHint=true, but the description adds substantial behavioral detail: soft-delete behavior, deletion of company_person relationships, preservation of linked companies, the self-deletion restriction, and the success/failure response shape. This goes well beyond what annotations provide and gives the agent an accurate model of 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 well-organized and front-loaded: purpose, explicit when-to-use, required parameter, behavioral side effects, restrictions, and return shape. Every sentence contributes useful guidance, with no unnecessary filler or redundancy that weakens the message.

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 tool with an output schema, the description covers the key operational context: scope, soft-delete semantics, cascade behavior, non-deletion of companies, self-deletion restriction, and error return shape. The input schema already documents the workspace_id and idempotency_key nuances, so nothing essential is missing from the overall tool definition.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly repeats the already-schema'd required person_id and adds little new parameter-level meaning; workspace_id and idempotency_key are fully explained in the schema itself. The behavioral notes about soft-deleting company_person relationships are context, not parameter semantics.

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

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

The description states a specific verb and resource: 'Delete a person (contact) from the current workspace (soft delete).' It is immediately clear this performs a soft delete on a person/contact, and the explicit behavior around company-person relationships and company preservation distinguishes it from sibling delete tools like well_delete_company and well_delete_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 a clear when-to-use rule: 'Use this tool when the user asks to delete, remove, or archive a contact.' It also notes the authenticated user cannot delete their own person record, which is a practical exclusion. It stops short of explicitly naming alternatives for related cases, such as well_delete_company for companies, 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?

Annotations already mark the call read-only, and the description goes well beyond that: zero months are included as 0 rather than omitted, unavailable is placeholder not measurement, partial excludes transactions with disclosure, change compares overlapping baselines, and trend means good/bad rather than direction. This materially prevents misreading the result.

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 paragraph earns its place: first sentence front-loads purpose, then each paragraph handles one output concept (amount/window, change/baseline, trend polarity, unavailable/partial, parameters, alternatives). The repetition of key warnings is deliberate reinforcement, not 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 subtle output semantics, output schema, and optional parameters, the description is complete: it covers window measurement, average divisor, placeholders, partial data, trend direction vs polarity, year/month override, alternatives, and single- vs multi-workspace auth. An agent has everything needed to call and interpret this 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?

Input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3; the tool description adds practical guidance by linking year/month to past-period measurement, months_back to window length default 3, and workspace_id to the multi-workspace authorization context. This is a modest addition above an already-rich schema, not a full transformation.

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 opens with a specific verb and resource ('Get the workspace's average monthly burn') and pins the exact definition to the app's avg-burn KPI tile. It explicitly contrasts with sibling tools at the end, so an agent can distinguish it from well_get_runway and well_get_cost_structure.

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?

Gives explicit when-to-use ('Use this instead of summing transactions yourself'), names alternatives for other questions (runway for months of cash left, cost structure for spend composition), and explains the multi-workspace condition requiring workspace_id. No exclusion is left to inference.

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, yet the description adds substantial behavioral context beyond them: sign conventions for 'increase'/'decrease' kinds (never report a decrease as negative), the special status of 'unexplained' as a non-cash gap, tolerance-based reconciliation wording, empty-steps meaning missing data rather than flat cash, the trailing multi-month period semantics, and the requirement to disclose hints. It also states the tool is a self-contained reconciliation and will not guess a workspace when several are authorized. No contradiction with annotations — 'this read' wording is consistent with readOnlyHint=true.

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 earns its place by preempting a distinct agent error: misreporting sign, folding 'unexplained' into flows, claiming flat cash on empty data, deriving the period from today's date, pairing with cash position, or tying out to cost structure. It is front-loaded with the core purpose, then proceeds logically through return semantics, reconciliation math, edge cases, parameter usage, sibling distinctions, and auth. Density is justified by the tool's semantic 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?

Despite an output schema existing, the description explains the steps array semantics, period fields, hints, empty-array behavior, reconciliation edge cases, multi-workspace auth, and sibling tool contrasts. It covers every call-relevant scenario an agent could encounter: absent period fields, missing anchors, timing-out reads, and authorization scope. Nothing needed to invoke 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 coverage is 100% and the schema descriptions already document year/month pairing and workspace_id conditions. The description adds genuine value on top: year+month select a past period rather than the live window, the returned period_start/period_end must be read from the response rather than assumed to match the request, and workspace_id is a disambiguation for multi-workspace tokens rather than a general selector. That is real semantic enrichment beyond the schema, though 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 opening sentence states a specific verb (get), resource (cash-flow bridge), and the core transformation (how opening cash became closing). It names the exact same steps as the Well app's waterfall chart, anchoring what the tool returns. Sibling differentiation is built in: the description explicitly contrasts this with well_get_cash_position and well_get_cost_structure, so an agent can select it without opening any 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?

Usage guidance is explicit and exhaustive: 'Use this instead of deriving flows from raw transaction reads'; 'do not also call well_get_cash_position' because it answers a different question; 'this is not a decomposition of well_get_cost_structure' and they will not tie out. It also gives precise conditions for passing year/month (bridge a past period vs. live window) and for workspace_id (omit when token authorizes one workspace, pass when several). Nothing is left to inference.

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 say readOnlyHint and destructiveHint, so the description carries the behavioral burden and excels. It discloses null-handling rules ('Do not fill the nulls in or treat a null as a zero'), the exact actuals/projection turn, the worst-case assumption with clamping, the anchor/basis interpretation pitfalls, the self-rendering chart card, and the 'do not re-plot' rule. These are meaningful behaviors beyond any annotation.

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 section earns its place given the nuanced output semantics. It is front-loaded with the core purpose and the most important behavioral constraint, then uses bullet lists and bolded cues to keep the dense details scannable. There is no fluff or tautology.

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

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

For a read tool with a rich output contract, the description covers return shape, null semantics, anchor/basis meanings, worst-case assumptions, hints handling, chart-card behavior, sibling routing, and workspace ambiguity — all without needing to reproduce the output schema. It is complete enough for an 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 input schema already fully documents workspace_id, including when to omit it and when it is required, so schema coverage is 100%. The description repeats this guidance but does not add new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate because the schema carries the parameter documentation burden completely.

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 cash-position forecast' and immediately scopes it as 'trailing actual month-end balances plus a worst-case projection forward.' It also names the exact chart series it mirrors, which distinguishes it from other cash-related tools, and later contrasts itself with well_get_cash_position and well_get_cost_structure on the period parameter.

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 alternative to manual projection ('Use this instead of projecting cash forward yourself'), clarifies when not to use it ('Takes no period'), and routes to siblings for related but different needs: 'For the single months-of-cash-left figure call well_get_runway; for the burn rate driving the decline call well_get_burn.' It also gives concrete caller guidance for workspace authorization, including when to pass workspace_id.

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 call read-only, and the description adds substantial behavioral context: unavailable/partial placeholder semantics, null balance_history meaning, backward-looking scope, live-only balance_history, and month-end historical granularity. 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?

Though long, the description is front-loaded with purpose and every paragraph earns its place: output interpretation, historical semantics, edge-case flags, and workspace/auth behavior. There is no filler or redundant marketing language.

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

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

For a read-only tool with zero required parameters, a full schema, and an output schema, the description is comprehensive. It covers return fields, edge-case flags, live vs historical behavior, workspace selection, and routes to well_get_runway when appropriate, leaving no material gap for an agent to guess.

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 documents all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantics on top: year+month means end-of-past-month as-of, balance_history is omitted for historical reads, and workspace_id selection rules for multi-workspace tokens.

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 ('Get the workspace's current cash position') and details exactly what it returns: the converted total, per-account breakdown, and the same computation as the Well app's KPI card. It also distinguishes itself from manual summing and nearby cash-related 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?

Explicitly tells the agent when to use this tool and when not: use it instead of summing account balances yourself, and call well_get_runway instead when a forward-looking figure is needed. It also gives concrete invocation rules for single-workspace vs multi-workspace tokens.

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

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

The description goes far beyond the readOnlyHint annotation by explaining the exact computation, the meaning of rung and label_provenance, the single-month period semantics, and the requirement to disclose hints. It also specifies how to handle missing period fields and machine-assigned labels, which an agent could not infer from annotations alone.

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 carries operational value; the core purpose and output are front-loaded, followed by caveats in a logical order. No filler, redundant restatements, or vague wording is present.

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 safety, the description adds all remaining operational context: return field meaning, period constraints, grouping provenance, label ownership, and multi-workspace handling. An agent has everything needed to invoke the tool correctly and present results accurately.

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?

Even though the schema already describes year, month, and workspace_id at 100 percent coverage, the description adds important runtime behavior: what happens when no data exists for a requested month, how the rung and label_provenance affect interpretation, and why workspace_id is required in multi-workspace contexts. This extra meaning is directly actionable.

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 (the workspace cost structure) and a specific computation: outflow for the latest closed month broken down by category, matching the Well canvas donut chart. It also signals the tool's scope by saying to use it instead of manually summing transactions, which separates it from generic query 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?

It explicitly tells the agent when to call this tool directly and when to add workspace_id for multi-workspace tokens, and it gives the year+month path for past months. It also warns to treat the returned period as authoritative and to avoid naming a period when the fields are absent, which is clear behavioral 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 this read-only, and the description adds substantial behavioral context: the exact return fields and their semantics, the note that colors are roles rather than raw token names, the consumption order for series, and the fallback behavior when color_scheme is absent. It also explains the token source cannot drift from the product.

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 every sentence earns its place: purpose, usage precondition, exclusion, return-field semantics, and provenance. It is front-loaded with the core purpose and then layers necessary detail 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 description fully equips an agent to decide when to call the tool, what to expect, and how to interpret edge cases such as missing color_scheme. An output schema exists, so the explicit return-field details are a bonus, not a necessity. Nothing material 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 input schema already provides 100% coverage for the single optional workspace_id parameter, describing it as optional and stating omitting it returns the same answer. The main description adds no further parameter-level meaning, which is acceptable because the schema handles it; 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 opens with a specific verb and resource: 'Get Well's colours, shape and type vocabulary'. It clearly differentiates the tool from all sibling data tools by positioning it as the design-token source for custom rendering, not for data retrieval.

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 guidance is explicit: 'Call this ONLY when you are about to render something yourself' and 'Do NOT use it to restyle a card a Well tool already drew.' It gives concrete conditions for use and non-use, making the agent's decision 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 declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavior beyond that: depth semantics, hard stop at depth 3, aggregate exclusion, 50-row cap per child collection, and the warning that omitting workspace_id may hit the token's primary workspace rather than the intended one. These are exactly the behavioral details an agent needs before calling.

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

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

The description is well-structured with a clear opening sentence, a comparison to alternatives, and a compact bulleted explanation of depth. Every sentence carries useful information, and the most important scoping details are front-loaded. It is longer than minimal, but the added detail is directly actionable.

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 exists, the description does not need to document return values. It covers all call-critical context: exactly what the tool reads, depth boundaries, exclusions, row caps, workspace targeting behavior, and when to switch to well_query_records. Nothing essential 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?

Schema coverage is 100%, so the schema already documents all four parameters. The description adds meaningful depth semantics beyond the schema, explaining what depth 1, 2, and 3 mean, the payload-size tradeoff, and the 50-row cap. The description does not add much for id/root, but the schema already covers them well, so a 4 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: 'Read ONE entity with its sub-resources nested in a single call.' It clearly states what the tool does and distinguishes it from the related well_get_schema and well_query_records flow, so an agent can tell it apart from the many sibling get_* 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 explicitly frames this tool as a convenience over well_get_schema + well_query_records and explains that it resolves field paths and returns a single expanded record. It also gives a concrete alternative for large child collections: use well_query_records on that child root. This is strong 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 declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: data is fetched fresh from Plaid on every call and never stored or stale, and the tool only works on Plaid connectors supporting the investments product. This is genuinely useful for an agent deciding whether to trust or cache the result.

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 first sentence immediately establishes purpose, followed by a compact workflow and a clear 'not for' list. The structure is front-loaded and every section earns its place without irrelevant detail.

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

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

For a read-only tool with an output schema and safety annotations, the description covers what is needed: how to prepare, what the call returns conceptually, and when to use an alternative. The exclusions remove the main ambiguity an agent would encounter among the sibling tools.

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 both parameters fully. The description reinforces the source of workspace_connector_id by tying it to well_list_connectors, but adds no new format or semantic detail beyond the workflow 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 uses a specific verb and resource: 'Get the live holdings/positions... for a connected Plaid investment account.' It clearly differentiates from siblings by explicitly excluding investment transactions and the MCP-transport passthrough tools, and by directing transaction queries to 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?

Provides an explicit numbered workflow: list enabled Plaid connectors, read the workspace_connector_id, then call this tool. It also states when not to use it and names the exact alternatives (well_list_connector_tools, well_invoke_connector_tool, well_query_records).

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 substantial behavioral context beyond the readOnlyHint: it explains the `anchor: null` case, warns against promoting a candidate to anchor, explicitly states that registry tax ids and registered addresses are not returned, and confirms no prerequisite call is needed. 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 thoroughly organized: definition first, usage guidance second, return shape and edge cases after. Every paragraph earns its place, and there is no fluff or repeated schema content.

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

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

For a simple read-only lookup with one optional parameter, the description is complete: return shape, null behavior, deliberate omissions, scoping, and usage rules are all covered. The output schema exists, so return value details do not need to be exhaustively repeated.

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% and the single optional parameter is well documented. The description adds extra semantic value by stating that both anchor and candidates are read from the same workspace the call is scoped to and that no other tool call is needed first.

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 which company the workspace itself is' and clarifies the distinction between `anchor` and `candidates`. This makes the tool's purpose immediately distinguishable from related tools like `well_set_own_company` and `well_get_entity`.

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 an explicit when-to-use: 'Use this whenever a question turns on "mine" versus "theirs"' with concrete examples, and an explicit when-not-to: 'Never decide which records are the workspace's own by comparing a company NAME.' It does not name an alternative tool by name, but the usage context is strong and would not mislead an agent.

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

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

The annotations only provide readOnlyHint and destructiveHint, so the description carries the full behavioral burden and exceeds it: it defines each status discriminator, explains partial-computation semantics, clarifies baseline/trend polarity, and warns that the forecast sibling's forward half is worst-case. It also discloses the design decision not to offer a burn-window option and why, which goes well 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 front-loaded with purpose, return semantics, and statuses before moving to edge cases and sibling routing. It repeats a couple of schema-level workspace/year-month rules and could be tightened, but the density is largely justified by the number of statuses and interpretation hazards.

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 output schema and annotations cover types and safety, while the description fills in all the interpretation and workflow context: status meanings, capped/infinite/insufficient-data handling, partial exclusion hints, baseline/treend semantics, auth behavior, and sibling routing. For a tool with this many edge cases, nothing an agent needs to call it 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%, and the schema already documents the year/month pairing, the omit-both-for-live rule, and the workspace_id authorization behavior. The description largely restates those rules rather than adding new per-parameter meaning, so the high-coverage baseline of 3 applies; the extra rationale about the absent burn-window option is not parameter semantics.

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

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

The first sentence names a specific read operation (get workspace cash runway), enumerates the exact metrics returned (cash on hand, trailing-3-month burn, months of cash left), and anchors it to the Well app's KPI cards. It also explicitly contrasts this with computing from raw account/transaction reads and later names the sibling tools it should not be confused with.

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 computing runway yourself, and call it directly when the token authorizes one workspace. It names alternatives with conditions — well_get_burn for a different burn window and well_get_cash_forecast for the monthly series — and explains why a burn-window parameter is intentionally absent here.

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 read-only and non-destructive, and the description adds meaningful behavioral detail: it returns fields with path, type, context, and enrichment provenance; explains that context helps pick the correct field and filters; and notes that workspace_id is irrelevant because the tool describes the token itself rather than workspace data. This goes well beyond the structured 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 USAGE, WORKFLOW, and return-format sections, and it front-loads the core purpose first. Every section earns its place, including the practical examples and the note about converting paths for well_query_records. It is dense but not padded.

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 schema-discovery tool with zero required parameters and an output schema, the description covers everything an agent needs: what roots to expect, how to invoke with or without a root, how to use the returned field metadata, how to map types to query operators, and how to translate paths for well_query_records. No critical guidance 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 input schema already provides 100% coverage for all three parameters, including root, depth, and workspace_id semantics. The description adds extra value with concrete root examples, the accounting-graph hint, operator selection by type, and path-to-array conversion. It does not add much beyond the schema for depth, but the schema already documents that sufficiently.

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 clear verb+resource statement: 'Discover available data types and fields,' then concretely demonstrates both invocation forms—no argument for all roots and with a root for field lists. It clearly distinguishes this tool from well_query_records by positioning it as the discovery step that feeds query construction.

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 WORKFLOW: call well_get_schema(root) first, select 5-15 fields, then call well_query_records. It also gives domain guidance, such as using the accounting graph for real financial statements instead of reconstructing them from raw invoices. This is specific, actionable, and tells the agent exactly when and how 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description goes further by explaining it 'reads only — it changes nothing,' never advances or re-renders the card, and provides detailed status semantics, count snapshot behavior, null handling, and the frozen graph. This is 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 detailed but every sentence earns its place, covering purpose, relationship to the sibling tool, status values, count semantics, and read-only behavior. It is front-loaded with the core purpose and structured with a bulleted list for statuses, making it easy to scan.

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

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

With an output schema present and annotations covering safety, the description fully explains the statuses, the meanings of the count fields, the content of records vs. graph, and the read-only nature. Nothing needed for correct invocation or interpretation 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 input schema already describes both document_id and workspace_id with 100% coverage. The description reinforces that document_id comes from well_create_statement_upload and mentions pre-allocation, but this information is already present in the schema. The description does not add substantially new parameter-level meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Read the outcome of a bank-statement upload started with well_create_statement_upload, by the document_id that tool returned.' It clearly distinguishes this from the sibling creation tool by noting it does not create or redraw the card.

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 call the tool: 'Call it once, shortly after the client has uploaded the file bytes, to learn what happened.' It also contrasts with well_create_statement_upload, saying that tool already renders a card and this one does not, and explains polling behavior for 'not_found_yet'.

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 destructive and open-world; the description adds that args pass straight through, that it only works on connectors exposing an MCP server with an enabled connection, and that it returns either the provider's tool result or {success:false,error} on failure or grant denial. It does not contradict the annotations and provides useful behavioral context beyond them, though it doesn't enumerate provider-side 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 front-loaded with the core definition, then the key exclusion, then a numbered workflow and constraints. It is longer than average, but the extra length is all operational guidance for an open-world invocation tool, with no repetitive 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 high-complexity dynamic tool, it covers purpose, when to use and not use, prerequisites, the exact upstream calls for parameters, and the failure return shape; the output schema handles return-value details. The only remaining details, such as workspace_id and idempotency_key behavior, are already fully documented in the input schema.

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

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

Schema coverage is 100%, so the schema already documents all five parameters; the description adds the crucial provenance: workspace_connector_id comes off an enabled row from well_list_connectors, tool must be one of the names from well_list_connector_tools, and args are passed straight through from that tool's live schema. This turns the parameters into an executable sequence.

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 concrete verb and resource: 'Run one tool on a connected provider's own MCP server' on behalf of the workspace connection. It differentiates itself from the large sibling set by explicitly saying it is not for reading financial data and routing those reads to well_query_records, so an agent can distinguish it from list/query 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?

It gives an explicit when: only for actions the user explicitly asked to take on the provider, and an explicit when-not: not for reading synced financial data, which should go to well_query_records instead. The numbered workflow names well_list_connectors and well_list_connector_tools as prerequisites, and the final conditions (MCP-server connector, enabled connection) tell the agent when the tool cannot be used.

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 though annotations already declare readOnlyHint=true and destructiveHint=false, the description goes far beyond them, explaining nuanced behaviors: the seven connection_status states and their user-facing implications, how null status with is_connected=true should be interpreted, how 'degraded' is resolved server-side, install_all_url null conditions, and is_preselected rules. This is rich behavioral disclosure that annotations alone could never 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 earns its place given the tool's complexity: 8 parameters, nuanced connection states, install-all behavior, and scoping rules. It is front-loaded with the core purpose, then organized into clear sections for entry fields, install_all_url, and scoping. The structure makes the density navigable rather than overwhelming.

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 full decision space: parameter usage, return-field semantics, edge cases like null install_url and empty from_selection results, sibling-tool routing, and even how to word the card via the scope field. With annotations and output schema present, nothing an agent needs to call this 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?

The schema covers 100% of parameters with its own descriptions, so baseline is 3. The tool description adds meaningful workflow semantics on top: when to choose kind versus q versus from_selection, that from_selection cannot combine with q/kind, and what 'bank' means in the data_domains context. It does not merely restate the schema, but it also does not need to add much more given the schema's already strong parameter documentation.

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 AND everything it has already connected, each with a one-click install deep link. It clearly distinguishes itself from siblings by explicitly naming well_list_connector_tools for live connection actions and telling the agent not to use well_query_records on workspace_connectors. The dual-scope purpose is 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 for every scenario: pass kind for a domain-scoped catalog, pass q for name search, omit both for the curated view, and use from_selection: true after a vendor pick. It also names exclusions and alternatives, such as 'Use well_list_connector_tools for a live connection's actions' and 'Do NOT read workspace_connectors records to work out connection coverage.' No inference is required.

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 mark this as read-only and non-destructive, and the description adds meaningful behavioral context beyond that: every response carries reconnect_url, and when success is false or status is 'need_reconnect,' the agent should surface the link. This gives the agent actionable knowledge about failure behavior and how to handle it.

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

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

The description is well structured with a clear purpose statement, numbered workflow, explicit usage rule, and a concise error-handling note. Every sentence adds useful information and the most important guidance 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?

The description is complete for a listing tool: it explains when to use it, how to obtain the required id, what the tool returns, and how to handle reconnect failures. The presence of an output schema means return-value details need not be repeated in the 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 description coverage is 100%, so the baseline is 3. The description adds context by saying workspace_connector_id comes from well_list_connectors and that args should be shaped from the input schema returned here, but most parameter meaning is already fully documented in the schema.

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

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

The description states a specific verb and resource: 'Discover the actions a connected provider exposes' and explicitly says the tool returns 'name + description + input schema' for each action. It also names sibling tools like well_list_connectors and well_invoke_connector_tool, making the purpose easy to distinguish.

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 a clear workflow: list connectors, pick the enabled provider, then call this tool, then invoke. It explicitly says to use it 'whenever you don't already know a connector's tool names — never guess them,' which is strong and direct usage guidance with no ambiguity about when it applies.

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 and destructiveHint, but the description goes well beyond them: it states the tool only reads and categorizes nothing, mints no task, and fetches no invoice. It discloses the per-month cost, the cursor-as-position paging semantics, the distinction between row counts and counterparty counts, and the fact that suggested_retrieval is provider-derived and unaffected by categorization. This adds substantial behavioral context beyond the structured 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 every paragraph earns its place: it front-loads the core purpose, structures the three modes clearly, and packs warnings and constraints into distinct labeled sections. The length is justified by the tool's combinatorial parameter behavior and the many traps an agent could otherwise fall into.

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 100% schema coverage, and the presence of an output schema, the description is complete. It covers all parameter combinations, paging behavior, cost implications, count semantics, null-value behavior, and the relevant sibling calls for adjacent operations. Nothing an agent needs to invoke this tool correctly appears to be 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?

Although schema coverage is 100%, the description adds significant semantic meaning by explaining how periods, uncategorized_only, and cursor combine into three valid usage modes. It clarifies that cursor is refused with periods, that periods accept 1-12 months with each month costing a separate read, and that uncategorized_only alone triggers a paged workspace-wide sweep. This goes far beyond the input schema's field-level 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 explicitly states the tool lists the workspace's counterparty companies and their company-level industry categories, with a specific verb and resource. It clearly differentiates the three modes (period, period+uncategorized_only, workspace-wide sweep) and distinguishes this tool from category-setting and catalog-reading siblings.

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 it for finding uncategorized suppliers, use uncategorized_only for work-remaining questions, use the sweep for workspace-wide checks, and do not use it to set categories or read the label catalog. It also names the exact sibling calls well_update_company and well_query_records for those adjacent needs, and states that no prerequisite call is required.

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 that the tool changes no data, does not mint tasks, does not start a close, does not connect anything, and does not fetch invoices. It also explains subtle behaviors such as one row per counterparty regardless of month count, row_count counting distinct counterparties, the transactions cap, and refusal of current/future/adjustment periods—far more than annotations alone 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 long, but the tool is genuinely complex and every major section earns its place: purpose, period selection, cost, result semantics, modes, categorization caveats, and side-effect guarantees. It is front-loaded with the purpose and would be a 5 but for some repeated warnings about one row per counterparty that, while useful, are stated more than once.

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

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

For a read-only list tool with six optional parameters and a rich output schema, the description covers all decision-relevant context: how to select periods, what rows represent, what each mode means, which caveats to surface to users, what counts as a complete result, and how workspace resolution works. Nothing material an agent needs to call it 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?

The schema already documents every parameter, but the description adds critical meaning the schema cannot express: the three mutually exclusive period-naming forms, the requirement that months must have ended, rejection of duplicate months and period 13, the per-month cost model, and how workspace_id resolves when omitted. This goes well above the baseline for a fully covered 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 first sentence states a specific verb and resource: 'List the supplier invoices a past period is still missing' with an explicit definition of what counts as missing. It also nails the cardinality ('one row per counterparty') and references a recognizable UI card, so an agent can distinguish this from generic list tools 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?

The description gives a clear use case ('which invoices am I missing for <month>?'), explains how to name periods, when to omit a period, refusal conditions, and even cost-aware guidance to request only the months the user named. It stops short of explicitly naming alternative tools to use instead, but it is exceptionally clear on when and how to invoke it.

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

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

Annotations already mark it read-only and non-destructive, and the description adds substantial behavioral context: the subtle 'selectable' vs 'inspectable' distinction, 'invoice_state: none' explicitly never meaning 'nothing missing', the cost model of one extra read per active month, and the null default_period behavior. No statement contradicts the readOnlyHint.

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

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

The description is front-loaded with the core purpose, uses clear section headers (PURPOSE, WINDOW, COST), and almost every caveat earns its place given the tool's semantic traps. It is long, and some field-by-field explanations could be deferred to the output schema, so it is not maximally concise for 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?

For a tool with six optional parameters, many sibling month-scoped tools, and subtle return-field semantics, the description covers selection intent, edge cases (future years, empty months, disconnected connectors), cost behavior, and defaults. Nothing an agent needs to call it correctly appears to be 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?

Although schema coverage is 100%, the description adds meaning beyond the schema: purpose must be set by the calling skill and never inferred from wording, year returns a full calendar year and future months are included but unselectable, months has a cost implication, and workspace_id falls back to the token's primary workspace. These are operational details the schema alone does not convey.

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 recent accounting months of the workspace' with close status, invoice-retrieval state, and work counts. It immediately states the tool's role ('Use this to ask the user WHICH month or months to work on before any close, review, or month-scoped read'), which sets it apart from siblings like well_list_missing_invoices that operate on an already chosen month.

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 says when to call it ('before any close, review, or month-scoped read'), what not to do ('do not guess a month, and do not derive one from today's date yourself'), and that no prerequisite call is needed. The PURPOSE section also tells the agent whether to pass 'close' or omit it based on the flow's intent, which is actionable selection guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail beyond that: the optional-workspace_id behavior, null semantics for identity and bank-transaction fields, deliberate omission of tax identifiers, and the meaning of has_bank_transactions as a signal rather than a definitive zero. It also discloses the session resync capabilities, leaving little hidden behavior.

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?

Though long, the description earns its length: it is front-loaded with the core purpose, then uses bullets for entry fields and paragraphs for nuanced semantics like bank-transaction detection and session resync. Every sentence carries actionable information, and the structure makes the complex content navigable rather than sprawling.

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 fully complete for a tool of this complexity. It covers the authorization context, the meaning of every returned entry field, the workspace_id selection behavior, bank-signal caveats, and session-staleness resync. Even with an output schema present, this description goes beyond what is needed and leaves no obvious agent question unanswered.

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%: the input schema already fully describes the only parameter, including that it is optional and that omitting it returns the same answer. The description reinforces this by explaining the workspace_id argument's role on other tools, but it does not meaningfully add new parameter-level semantics beyond what the schema already provides.

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

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

The description opens with a clear verb-resource statement: 'List the workspaces this connection is authorized to access.' It specifies the resource, the authorization scope, and immediately positions the tool as the first step when a token may span multiple workspaces, distinguishing it from workspace-scoped operations like well_switch_workspace or well_get_own_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?

It gives explicit when-to-use instructions: 'Use this FIRST when a single token may cover more than one workspace,' and 'Call this any time you need to resync with clicks you may have missed.' It also explains when workspace_id can be omitted versus when it must be provided, giving actionable context for read and write tools across the API.

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 goes well beyond that. It explicitly states 'THIS TOOL LAUNCHES NOTHING', guarantees mode is always 'preview' and nothing_launched is always true, explains refusal and null-sum behavior, and details the collect_url semantics including the 25-portal ceiling and unaddressable vendors. There is no contradiction between the description and 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 organized into clear thematic paragraphs and front-loads the core purpose, but it is very long and contains some redundant restatement — for example, the point that 'vendors' is every vendor of the rows this call covers is made multiple times. The density is mostly justified given the tool's complexity, but tightening the repeated clarifications would improve readability without losing meaning.

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 this complex, the description is remarkably complete. It covers output semantics for vendors, upload_rows, connect_rows, counts, months, periods_covered, selection_scope, collect_url, url_source, hints, and the uncategorized-spend limitation. It also explains what the tool does not do, such as launching tasks or fetching invoices, and how to handle scoped results. The presence of an output schema lowers the burden, but the description goes far beyond that baseline.

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 schema description coverage is 100%, the description adds substantial meaning beyond the schema. It explains that the period must be named exactly one way, gives concrete examples for calendar versus fiscal versus periods arrays, clarifies the fallback to user-selected months when no period is named, and warns that each month is a separate read so the agent should ask only for the months actually named. It also adds refusal semantics for duplicates, future months, and the adjustment period that the schema alone does not fully convey.

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 pair — 'Preview which vendors a past period is still missing supplier invoices from' — and adds scope by stating what the preview is for, what it covers, and what it never launches. It also differentiates itself from the sibling well_list_missing_invoices by explicitly pointing there for a fresh card and by emphasizing that this call only previews and runs nothing.

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 trigger: 'Use it for "what would happen if I fetched <month>'s missing invoices?" before anything runs.' It also states when the call refuses (no period named and no selected months, current/future months, adjustment period 13, duplicate months), tells the agent not to request a whole year just to be safe, and names well_list_missing_invoices as the alternative when a fresh card is needed. It even instructs that launching agents is not available on this surface, so the preview must be presented as information only.

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 strongly reinforces read-only behavior. It adds substantial behavioral detail beyond the annotations: `fields` is additive and never changes what the user sees, every response carries totalCount and records_url, nextCursor should not trigger pagination for aggregates, and same-entity name filtering can silently drop rows.

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 structured with clear sections: WORKFLOW, ROOTS, CATEGORY CATALOGS, CONNECTED TOOLS, RULES, ONE CALL, FILTERING, SORTING. It front-loads the most important workflow guidance and every section carries operational value rather than filler or restatement of the schema.

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 9 parameters, nested objects, an output schema, and a large sibling set, the description is exceptionally complete. It covers root selection, field discovery, filtering operators, sorting, pagination semantics, return shape, anti-patterns, and sibling-tool routing, leaving no critical ambiguity for an agent selecting or invoking this tool.

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

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

Schema coverage is 100%, but the description adds meaning well beyond the schema. It explains field-path conversion ('invoices.issuer.name' → ['invoices', 'issuer', 'name']), safe vs type-restricted whereClause operators, the default limit of 50 and max of 500, the semantics of partyScope, and the additive behavior of `fields`.

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

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

The description opens with 'Query records from Well's database', giving a specific verb and resource, and goes further by enumerating all 33 roots. It explicitly differentiates from sibling tools: 'do NOT use this tool to show the user what they have connected — call well_list_connectors instead' and contrasts it with well_invoke_connector_tool for provider 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 and when-not-to-use guidance: use it for data Well already syncs, never for provider actions, and never for showing connection status. It also prescribes a concrete workflow: call well_get_schema(root) first, then add only needed fields via `fields`, with examples for both display and targeted-answer 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?

The annotation destructiveHint=true already signals that this operation deletes data. The description adds valuable context by specifying that the action is scoped to a single channel row and explicitly warns 'NOT the parent', preventing accidental deletion of a company or person. It also identifies the underlying HTTP method as DELETE. No contradiction with annotations exists.

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: purpose, endpoint mapping, and critical parameter guidance are each covered in short, purposeful sentences. There is no filler, and the most operationally important warning about channel_id is given prominent placement.

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 destructiveHint annotation, full schema coverage, and presence of an output schema, the description provides enough context for correct invocation. It explains the deletion target, the endpoint, how to obtain the required channel_id, and the parent types. Optional parameters such as workspace_id and idempotency_key are fully documented in the schema, so the description does not need to repeat them.

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 guidance beyond the schema by clarifying that channel_id belongs to the specific channel row, not the parent record, and by recommending a lookup path through well_query_records. This helps the agent avoid a common misuse of the parameter even though the schema already describes it as the channel row UUID.

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

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

The description begins with a clear, specific statement: 'Remove a contact channel from a company or person.' It names the exact endpoint pattern and enumerates the channel types, making it obvious this is a targeted delete operation on a channel row, not on the parent company or person. This distinguishes it well from siblings like well_add_contact_channel 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?

The description gives clear procedural guidance: pass the channel_id, not the parent, and find the correct channel_id by reading the parent with well_query_records. This tells an agent how to obtain the required identifier before invoking the tool. It does not explicitly state when to prefer this tool over alternatives, but the resource-scoped endpoint and channel-specific language make the intended use 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?

Beyond annotations, the description details the consequences of each action: approve flips the link to active, reject dismisses the match without silent re-surfacing. It also discloses independent resolution and partial-failure behavior, which is valuable for an agent invoking a write operation.

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, front-loaded with the core operation, and uses a bulleted list for action semantics. Every sentence adds information; there is no filler or repetition of schema details.

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

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

Given the annotations, input schema, and output schema, the description covers the operation's source, per-action effects, failure semantics, and batch behavior. An agent has enough context to select and invoke the tool correctly without needing to infer hidden behavior.

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

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

Schema coverage is 75%, and the schema already documents task_ids, workspace_id, and idempotency_key well. The description adds meaning to the action parameter by defining approve and reject outcomes, and it clarifies that each task_id resolves independently. This is useful context beyond the raw 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 names a specific action (Approve or reject) on a specific resource (reconciliation review tasks) and ties the source to well_run_register_diff or the in-app review queue. This clearly distinguishes it from sibling tools like well_run_register_diff 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 gives clear context for when the tool applies: tasks from well_run_register_diff or the review queue, with approve/reject semantics. It does not explicitly contrast this with the sibling well_resolve_register_diff_gap, so there is no explicit when-not-to-use statement, but the source and operation 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 only provide readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining behavior. It does so well by stating that the operation fails with an error rather than silently no-op'ing when gap posting is disabled, accounts don't belong to the connector, or accounts no longer resolve in QuickBooks. It stops short of describing post-success state changes, but the failure semantics are a meaningful addition.

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-organized: purpose first, then requirements, then lookup instructions, then failure conditions. Every sentence earns its place, and the structure front-loads the most decision-relevant 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 write operation that depends on external QuickBooks resolution and workspace/account scoping, the description covers prerequisites, lookup procedure, validation constraints, and failure modes. The presence of an output schema means return values are documented elsewhere, so nothing essential is missing for an agent to invoke this 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 the baseline is 3; the description adds value by explaining that bank_ledger_account_id and category_ledger_account_id must be UUIDs (not names), must be exact, and must belong to the gap's register connector. This goes beyond the terse schema descriptions and materially reduces misuse risk.

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: 'Post a well_run_register_diff gap ... into QuickBooks as a Purchase or Deposit.' This clearly identifies the action, the target system, and the record type. It also distinguishes itself from likely siblings like well_run_register_diff by framing this as the follow-up resolution step for a 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 gives explicit usage prerequisites: both ledger account IDs must be exact UUIDs and must be looked up first via well_query_records scoped to the register connector, with a warning never to guess or fuzzy-match. It could add an explicit 'use this when...' contrast with well_resolve_reconciliation_task, but the lookup-first guidance and failure preconditions provide strong practical direction.

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 extensively discloses side effects beyond the annotations: matches become review tasks with candidates attached, gaps are minted as proposals, contended transactions are never minted, and results are persisted. It even explains the two underlying causes of contended results, including provider failures and invalid model responses.

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 organized with a summary sentence followed by four focused bullet points, each covering a distinct output category. Although long, every sentence contributes operational detail, and the feature-disabled note is appropriately placed at the end. Nothing feels redundant.

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 every outcome class: raised_for_review, missing_in_register_ids, gaps_proposed, gaps_already_proposed, contended_in_register_ids, and unexplained_in_register_ids, plus the disabled-return behavior. Since an output schema exists and parameter schemas are complete, no essential 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%, so the schema already documents all five parameters. The description adds no additional parameter meaning beyond mentioning QuickBooks as an example register, which the schema already includes. 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 opening sentence states the specific verb 'Diff' with a clear resource: bank transactions against accounting-register transactions, and notes that the result is persisted. This distinguishes it from sibling follow-up tools like well_resolve_reconciliation_task, which the description explicitly names as later 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 practical workflow guidance: no automatic linking, resolution via well_resolve_reconciliation_task and well_resolve_register_diff_gap, and advice to re-run later for contended_in_register_ids. It also flags the feature-off disabled return. There is no sibling diff tool, so explicit alternative selection is unnecessary.

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, the description discloses that this is an accounting-critical write that overwrites the workspace's legal identity, clears fields when the anchor moves, records a manual-confirm audit row, and syncs the billing customer name. It also states what it does not do—re-post journal entries—and that unauthorized callers are refused, not silently ignored. These details align with destructiveHint=true and add significant safety 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 well-structured with bolded section labels and front-loads the core purpose before diving into details. Each sentence adds a distinct, non-redundant fact: prerequisite, side effects, boundary of behavior, authorization, and dependency. The length is justified by the sensitivity and complexity of the write operation.

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 prerequisites, authorization, side effects, what the operation does not do, and a hard-gate dependency on well_start_close. With an output schema present and annotations aligning with the described behavior, nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

The schema already documents all three parameters at 100% coverage, but the description adds crucial semantics for company_id: it must already exist in the workspace, can be obtained via well_query_records or well_create_company, and this tool never creates one. It does not add extra meaning for workspace_id or idempotency_key, but the schema descriptions for those are sufficient.

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 precise operation—setting which existing company is the workspace's own-company anchor—and distinguishes itself from creation tools by explicitly saying 'this tool never creates one.' It also names related tools like well_query_records and well_create_company for obtaining the company_id, making its role clear relative to siblings.

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

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

The description gives explicit guidance: company_id must reference an already-existing workspace company, how to obtain it, and the instruction to confirm the exact company with the user before calling. It also specifies the workspace owner/admin role restriction and notes that well_start_close hard-gates on this anchor, so an agent knows the prerequisite and consequence 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?

Beyond the annotations (readOnly=false, destructive=false), it clarifies that the write touches session context only ('This changes nothing in the user's data'), explains pin/queue replacement, stale-workspace refusals, and acknowledgement clearing on switch. 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 long and occasionally repeats the scoping phrase 'the workspace this call is dispatched to,' but it is front-loaded, organized by parameter, and each section covers a distinct behavioral edge case. The complexity of the tool justifies most of the length.

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

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

For a stateful 7-parameter tool, the description covers the no-argument call, universal workspace targeting, auth constraints, the changed return field, and links to reporting/reading siblings. With full schema and an output schema present, nothing needed to invoke 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 coverage is 100%, but the description adds substantial cross-parameter meaning: the first workspace_ids entry becomes the pin while the rest replace the queue, counterparty_periods never becomes the session's selected months, and ack/counterparties are scoped to the dispatched workspace. This goes well beyond the schema field descriptions.

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

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

The description opens with 'Write this connection's session context' and enumerates exactly what gets recorded: workspace pin/queue, months, counterparties, and step acknowledgements. This is a specific verb+resource and clearly distinguishes the tool from sibling read/list 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?

It states when the tool fires ('the tool the widget cards call when the user CLICKS them'), when to omit args entirely, and gives explicit exclusions: 'Send it only to change the workspace,' 'Never re-pin the workspace this connection already holds,' and 'never to bound a counterparty pick.' It also names well_list_workspaces as the way to see authorized workspaces.

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