Well

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

Goes beyond annotations by disclosing POST semantics, phone normalization (leading '+' added), defaults (label 'work', platform 'website'), and the error case for unsupported phone on company. No contradiction with readOnlyHint=false or destructiveHint=false.

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?

Front-loaded purpose, then endpoint, then a compact mapping list, and a note with edge cases. Each line adds value, no filler, well organized for scanning.

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 100% schema coverage, an output schema, and annotations already covering read-only/destructive hints, the description covers the essential usage rules, per-channel fields, defaults, and a key exclusion. Generic auth/rate-limit details are not needed here.

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

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

The channel-to-field mapping (email→email, phone→e164_number, web_link→url, location→city/country) is essential for correct invocation and goes well beyond the generic schema descriptions. It also clarifies optional fields and defaults.

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

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

States a specific verb and resource: 'Add a contact channel to a company or person.' The REST endpoint reference and channel-type enumeration further distinguish it from read/remove siblings like well_query_records and well_remove_contact_channel.

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 notes when not to use (phone on company) and provides an alternative for reading (well_query_records). This gives clear when/how vs. when-not guidance beyond the title.

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 destructive, and the description goes well beyond that by explaining exactly what changes: 'This changes figures, not just a label.' It details how marking an account as workspace affects the internal-transfer rule and can quietly remove real spend from burn, and it notes that cross-workspace companies are refused rather than resolved. No contradiction found.

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 well-structured: purpose first, then use case, then required-field rule, enum semantics, and a prominent warning in bold. Nearly every sentence earns its place, though the cautionary section could be tightened slightly without losing impact.

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 this is a write tool with cross-entity side effects, the description covers when to call it, prerequisites, enum semantics, constraints, error behavior, detach semantics, and the return shape. It is complete enough for an agent to invoke it correctly without needing additional context.

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

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

Schema coverage is 100%, but the description adds critical semantics beyond it: the constraint 'account_id, plus at least one of company_id or ownership' is not in the schema's required list. It also explains the meaning of each ownership enum value and clarifies that passing company_id: null detaches, which adds real value over the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Attach a bank account to a company, and say whether the workspace owns it.' This clearly distinguishes it from the sibling well_assign_missing_invoice_owners, which targets invoice ownership, not account ownership.

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 to use this tool when an account carries no company or when ownership is still unknown. It also warns against guessing and tells the user to leave ownership as 'unknown' instead. However, it does not name concrete sibling alternatives for other scenarios, so the when-not guidance is implicit rather than fully explicit.

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

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

Beyond the destructiveHint and readOnlyHint annotations, the description discloses that the write replaces the entire owner set, removes unspecified owners, creates one proof task per distinct person with a single resolving invoice, and refuses the whole batch with specific refusal reasons for closed periods, out-of-workspace people, and non-owned transaction ids. 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, but it is front-loaded with purpose and required parameters, and every paragraph adds non-redundant behavioral or failure-mode information. A few stylistic redundancies (repeated NOT_FOUND reason, all-caps emphasis) keep it from being 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 destructive multi-parameter write tool with an output schema, the description covers prerequisites, set-replacement behavior, refusal semantics, frozen-period handling, and the get-people workflow. Optional workspace/conversation/idempotency semantics are fully handled in the schema, so no critical calling information 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 all five parameters (100% coverage), so the baseline is 3; the description adds crucial semantics for transaction_ids and owner_person_ids: ownership is a SET, not a single owner or card rule, the write REPLACES the set, and the fan-out is for accountability rather than N independent collections. This materially improves parameter understanding beyond the schema.

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

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

States a specific action ('Set the owner SET') on a specific resource ('missing-invoice TRANSACTIONS') and explicitly claims it is 'the only write for missing-invoice ownership,' distinguishing it from the read-only sibling well_list_missing_invoice_owners and other write 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?

Provides explicit selection guidance: it is 'the only write for missing-invoice ownership,' names the source tool well_list_missing_invoice_owners for transaction_ids, instructs to get people via well_query_records, and explains the empty-array clearing behavior. This gives the agent clear when-to-use and prerequisite 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?

Despite annotations already marking readOnlyHint=false and destructiveHint=false, the description adds substantial behavioral context: single-use token, one-hour expiration, returns per-file document IDs, refused tokens are final, and failed files need manual re-request. 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 information-dense with no fluff. Each sentence adds value: token usage, polling, failure handling, and parameter nuances are all covered. It is front-loaded with the core concept and structured logically.

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 four parameters, an output schema, and complex token lifecycle, the description covers every aspect an agent needs: when to call, how to handle results, failure modes, and parameter usage. Nothing critical is missing, and the output schema covers return structure.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant meaning: claim_token must be exactly as written, workspace_id has omission vs. requirement rules, conversation_id propagation details, and idempotency_key semantics. This far exceeds baseline.

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

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

The description states a specific verb ('Claim'), resource ('every bank statement the user dropped on Well's website'), and scope ('in one visit'). It clearly distinguishes from siblings like well_upload_statement_bytes or well_get_statement_import_result, leaving no ambiguity about what the tool does.

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 to call once per token, never per file, and to poll well_get_statement_import_result for each result. It also gives clear when-not-to-use guidance (refused tokens are final, ask user to attach files, never retry), naming an alternative action and a sibling tool.

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

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

The description discloses the async enrichment behavior (logo, domain, industry, etc.), immediate availability, and the need to re-query for enriched fields. It also specifies the return format. These go well beyond the annotations, which only indicate non-read-only and non-destructive nature.

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

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

The description is three short paragraphs: purpose, required/optional, and behavioral notes. It is front-loaded with the purpose and is free of redundant phrasing. Every sentence adds value, making it concise and well-structured.

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

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

The description covers the essential context: what it does, when to use it, required vs optional params, async background processing, availability, and the return shape. It is complete for an agent to invoke the tool correctly, with schema handling the fine-grained parameter details.

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

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

The schema has 100% parameter coverage with detailed descriptions, so the baseline is 3. The description only repeats the required/optional status of name and description, adding no new meaning beyond what the schema already provides. It does not elaborate on workspace_id, conversation_id, or idempotency_key, but the schema handles these adequately.

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

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

The description opens with a clear verb+resource ('Create a new company') and explicitly ties it to user intent ('create, add, or register a new company'). It distinguishes itself from siblings like well_create_company_candidate by specifying the current workspace, though it does not name alternatives directly.

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

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

The description provides explicit when-to-use guidance ('Use this tool when the user asks to create, add, or register a new company') and clarifies scope ('current workspace'). It does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations only indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds critical behavioral details: it requires workspace owner/admin role, a caller without it is refused (not silently ignored), the tool hydrates the registry hit, and it returns linked_to_existing_child when the company already has a workspace. This goes well beyond the annotations and fully discloses side effects and access requirements.

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

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

The description is well-structured with a clear opening, a REQUIRED callout, and short paragraphs. Every sentence carries essential information: purpose, required parameter, role constraint, edge case, and user-confirmation instruction. There is no redundancy or filler, and key constraints are front-loaded.

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

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

Given the tool's complexity—a write operation with role restrictions and an output schema—the description covers all critical aspects: the workflow position, required input, permission requirements, refusal behavior, the linked-to-existing-workspace edge case, and the next step. It does not need to explain the output schema because that is provided separately. The description is complete 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 100%, so the baseline is 3. The description adds value by explaining that registry_ref is the id from well_search_company_registry and that the tool 'hydrates that hit', which clarifies the parameter's role in the flow. It also ties the returned candidate_id to the next tool. While the schema already documents each parameter, the description enriches the context of registry_ref and the 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 precise verb and resource: 'Mint a company candidate from a registry hit', and places it in the workflow: 'the step between finding the company and creating its workspace.' It explicitly differentiates from the sibling well_create_company_workspace by naming the next step, and the phrase 'primary (own-company) candidate' distinguishes it from well_create_company. The purpose is unambiguous and distinct.

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

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

The description gives explicit when-to-use guidance: when you have a registry hit and need to mint a candidate. It names the exact sibling to call next (well_create_company_workspace) and provides an exclusion condition: if the result carries linked_to_existing_child, switch to well_switch_workspace instead. It also instructs to confirm the company with the user before calling. No ambiguity remains.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral context: it explains the sequence of internal actions (mints workspace, projects accounting settings, anchors own company, writes lineage), and discloses that non-owners/admins are refused rather than ignored. It also reinforces idempotency by stating repeated calls return the same child with already_anchored true. No contradictions with annotations.

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

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

The description is well-structured: purpose, required parameter, behavior, permissions, and user confirmation. Each sentence earns its place, and the key prerequisite and idempotency are front-loaded. The line breaks improve scannability. It is detailed yet not verbose.

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

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

Given the complexity of a multi-step workspace creation, the description covers all essential operational aspects: what it does, prerequisites, sequence, permissions, idempotency, and confirmation. An output schema exists, so return format need not be described. It also references the relevant sibling tool for switching workspace, making it self-sufficient for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context for candidate_id (explicitly says it comes from well_create_company_candidate) and explains idempotency behavior that maps to idempotency_key. However, it does not elaborate on workspace_id or conversation_id beyond the schema. It adds marginal value but does not significantly compensate for any gap since the schema already covers everything.

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 the company workspace from a candidate, the step that turns a picked company into a workspace the close runs in.' It clearly differentiates from well_create_company_candidate by naming it as the prerequisite and from well_switch_workspace as a follow-up. An agent can tell exactly what this tool does 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?

Provides explicit usage guidance: requires candidate_id from well_create_company_candidate, describes the flow (mints workspace, anchors company, writes lineage) and mentions the follow-up well_switch_workspace. It also states permission requirements and instructs to confirm with the user before calling. This is explicit when-to-use and even what to avoid (silent refusal).

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 state readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing that the tool refuses to overwrite a REAL ingested document, that it conditionally uses a logo or issuer name as text, and that 'Never promise a logo.' It also explains link expiry semantics for signed URLs versus app_url. This is strong behavioral transparency beyond what annotations provide.

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

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

The description is long but organized into clear functional blocks: the action, the letterhead caveat, usage guidance, refusal condition, and return-value explanation. It front-loads the core purpose in the first sentence, and the later detail about URLs and expiry is genuinely useful rather than filler. Minor inefficiency exists because some return-shape details overlap with the output 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 the tool's moderate complexity, the output schema, and the annotations, the description covers all essential operational context: prerequisites (invoice must exist), refusal conditions (already linked to a REAL document), side-effect expectations (does not send), return shape, and link semantics. An agent has enough information to decide when to call it and what to expect.

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 75%, and the schema already thoroughly documents workspace_id, conversation_id, and idempotency_key. The description adds the key precondition that invoice_id must reference an existing invoice, but it does not add much semantic value beyond the schema for the optional parameters. This is adequate but not exceptional.

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: 'Render an existing invoice as a print-ready PDF and attach it as the invoice's source document.' This clearly distinguishes the tool from siblings like well_create_invoice_from_data (creates an invoice from data) and well_upload_document (uploads arbitrary documents), and the first sentence alone tells the agent exactly what the tool does.

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 usage trigger: 'Use this tool when the user asks to generate, render, or attach a PDF for an invoice that already exists in the workspace.' It also states a clear when-not behavior: 'This does NOT email or send the invoice anywhere.' It stops short of naming alternative sibling tools explicitly, so it has clear context and exclusions but not full alternative routing.

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

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

Annotations already indicate destructiveHint=false and readOnlyHint=false, so the description doesn't need to repeat those. It adds important behavioral details: that one call is the whole write, that re-resolving without company_id can attach to wrong company or create duplicates, and that patching after create causes two confirmations. It does not mention idempotency_key but that is in the schema. Slight deduction for not mentioning the persistence pipeline in detail, but it's clear enough.

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

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

The description is well-structured with clear sections and bullet points, but it is quite long. It front-loads the core purpose and then provides detailed usage guidance. While lengthy, every sentence adds value, and the structure helps readability. Minor deduction for length, but it's justified by the 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?

The description covers the tool's purpose, usage, key parameters, and integration with sibling tools. It explains edge cases like re-resolution and workspace selection. The output schema exists, so return values need not be described. For a complex write tool, this is remarkably complete.

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

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

Schema description coverage is 54%, and the description compensates by explaining key parameters like company_id (always send when known), status (set it here not via update), and workspace_id (omit when single workspace). It also explains line_items, totals, and payment_means structure. However, some parameters like reference_number, issue_date, and currency are only described in schema, but the description covers the important ones.

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

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

The description clearly states the tool creates an invoice from structured data extracted via OCR, not from a file. It lists the fields to be filled and explicitly differentiates from sibling tools like well_create_invoice_document (which likely handles file uploads) and well_update_invoice (which is for patching).

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 to use this tool for the whole write operation, when to pass a status (when user asked for draft), when to pass company_id (when already found), and warns against creating and then patching. It also tells when to omit workspace_id based on token authorization. This is exemplary guidance.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description correctly implies a write operation. It adds valuable context beyond annotations by noting that 'enrichment runs asynchronously in the background' and describing the success/failure return shape. This gives the agent awareness of post-creation side effects without contradicting the annotations.

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

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

The description is compact—roughly five sentences—and front-loaded with the core purpose, followed by usage, required/optional fields, side effects, and return value. Every sentence earns its place, with no filler or redundant restatement of the title.

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 8-parameter schema where most parameters have rich descriptions, and the presence of an output schema, the description covers the essentials: purpose, usage, required/optional fields, and asynchronous enrichment. It does not restate return details (covered by output schema) nor parameter semantics (covered by schema descriptions). The only minor gap is not explicitly mentioning the special workspace_id/conversation_id behavior, but those are fully documented in the schema, so the description stays sufficiently complete.

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

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

Schema description coverage is 75%, with detailed descriptions for workspace_id, conversation_id, idempotency_key, and the name fields. The description highlights first_name as required and last_name/job_title as optional, but this is already in the schema. It does not add meaning for email, phone, workspace_id, conversation_id, or idempotency_key, leaving the schema to carry most of the 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 action and object: 'Create a new person (contact) in the current workspace.' It also provides common user intents ('add, create, or register') and clarifies the resource as a person versus other entities like companies. The verb 'Create' is unambiguous and distinct from sibling create tools like well_create_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 explicitly states 'Use this tool when the user asks to add, create, or register a new contact, employee, or person,' which gives clear context for when to select it. However, it does not explicitly contrast with alternatives like well_add_contact_channel (for adding channels to an existing person) or well_update_person, so it relies on implied exclusions rather than naming them.

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 mark non-read-only, non-destructive, non-open-world. The description adds critical behavioral details: token expiration (15 min), one-time burn, pre-allocated document_id, and that a premature result call returns 'not_found_yet' rather than an error. This goes well beyond the annotations and gives an agent a clear model of what happens.

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 sentence earns its place. It's front-loaded with the core purpose, then flows logically through usage, token behavior, and response semantics. No filler, and the structure mirrors the criticality of the 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?

For a tool with this complexity (mint, upload, poll), the description is fully sufficient. It covers the upload flow, token constraints, pre-allocation, card behavior, and how to follow up. Nothing an agent needs to invoke and use 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 coverage is 100% — all three parameters have rich descriptions covering workspace_id, conversation_id, and idempotency_key. The description adds little to these, only indirectly referencing workspace by mentioning token authorization. Per the baseline for full schema coverage, a 3 is appropriate; the schema already carries the semantic weight.

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 action ('Mint a one-time, short-lived upload slot for a bank-statement file'), clearly identifies the target resource, and immediately distinguishes it from direct-upload siblings by stating that file bytes do not travel through the model. It's specific and not a tautology.

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

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

Explicitly states when to use this tool ('when the user has a statement file... to import') and gives precise follow-up instructions (call well_get_statement_import_result once after upload, card polls itself, only call again if user asks). It also clarifies the one-file-per-call rule and token lifecycle, leaving no ambiguity about the intended workflow.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, but the description goes far beyond by detailing the soft-delete semantics, what is deleted (company and company_person relationships), what is preserved (people, invoices, documents), and the exact return shape. This is rich behavioral disclosure.

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

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

The description is front-loaded with the core purpose and usage trigger, followed by behavior and return values. It is concise, though the 'REQUIRED: company_id' line is slightly redundant given the schema's required list. Overall efficient and well-structured.

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

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

Given the destructive action, the description covers what happens to related data, what is preserved, and the success/failure return format. The output schema exists, parameters are fully described in the schema, and annotations carry the safety profile. 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?

Schema description coverage is 100%, with all four parameters (company_id, workspace_id, conversation_id, idempotency_key) well-documented in the schema. The description adds no new parameter-level meaning beyond restating company_id as required, which is already in the schema. Baseline 3 is appropriate.

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

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

States exactly what it does: 'Delete a company from the current workspace (soft delete).' The verb 'delete', resource 'company', scope 'current workspace', and the soft-delete qualifier differentiate it from sibling delete tools like 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?

Gives explicit triggers: 'Use this tool when the user asks to delete, remove, or archive a company.' It clearly identifies the intended context and required parameter, though it does not explicitly name alternatives or exclusion cases. Clear context without exclusions.

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

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

The description adds significant behavioral detail beyond the annotations: it explicitly says 'soft delete', explains that linked line items and payment_means rows are NOT cascade-deleted and remain orphaned, and notes the deletion is reversible only at the database level. This goes beyond the destructiveHint=true annotation, which only signals destructiveness. It does not contradict the annotations and provides valuable side-effect information.

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

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

The description is concise and front-loaded with the core purpose and the required parameter. The body consists of two sentences that efficiently cover the soft-delete behavior and its side effects. The 'REQUIRED: invoice_id' line is a small redundancy with the schema but serves as a useful reminder. Overall, it is well-structured and wastes no words.

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 4 parameters and an output schema, the description covers the essential behavioral caveats: soft delete, non-cascade, and reversibility constraints. It does not need to explain return values because an output schema exists. The parameter semantics are fully covered by the schema, and the description provides the missing operational context (orphaned rows). It is adequately complete for agent invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only restates 'REQUIRED: invoice_id', which the schema already documents as required. It does not add any additional meaning for workspace_id, conversation_id, or idempotency_key beyond what the schema provides. No new parameter semantics are introduced.

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 ('Delete an invoice from Well') and identifies the resource (invoice), while also specifying 'soft delete' to set it apart from a hard delete. This distinguishes it from sibling delete tools like well_delete_company and well_delete_person. The purpose is unambiguous and directly tied to the tool name.

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?

There is no explicit guidance on when to use this tool versus alternatives, such as well_update_invoice or well_delete_company. The description does not state prerequisites or scenarios where this tool is preferred. The only contextual hint is the resource name, leaving the agent to infer usage without direct 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 only mark destructiveHint=true, and the description adds substantial behavioral context beyond that: soft-delete semantics, deletion of company_person relationships only, linked companies NOT being deleted, the self-delete restriction, and the exact success/failure return shapes. This is exactly the kind of context an agent needs for a destructive 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 tightly structured and front-loaded, with the core action and trigger condition first, followed by key constraints and the return contract. Every sentence contributes useful information, and the return format is clearly specified without excess.

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 rich schema descriptions for all four parameters and an output shape already stated in the description, nothing essential is missing. The description covers side effects, restrictions, and error handling, making it fully actionable for an agent.

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

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

Schema description coverage is 100%, and the schema already documents person_id, workspace_id, conversation_id, and idempotency_key in detail. The description restates person_id as required and adds deletion-related behavior, but it does not add new parameter semantics beyond what the schema provides, 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 states a specific verb and resource ('Delete a person (contact) from the current workspace') and distinguishes the tool by adding 'soft delete' plus the scope of what is and is not deleted. This differentiates it clearly from sibling 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?

It explicitly tells an agent when to use it: 'Use this tool when the user asks to delete, remove, or archive a contact.' However, it does not mention when not to use it or name alternatives, such as removing only a contact channel via a sibling tool, so it stops short of a full 5.

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

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

Beyond the annotations, the description discloses idempotent reuse via already_active, that no browser actions are launched synchronously, the 25-portal collect_url ceiling, provider: null fallback to manual upload, and omitted/unaddressable counterparty handling. These are behavioral traits an agent would not infer from the schema or annotations.

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

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

The description is lengthy but every sentence carries necessary behavioral or routing information. It front-loads the core purpose and follows with usage constraints, then edge cases taxonomically (already active, portal ceiling, null provider, unaddressable). No filler or repetition 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 the tool's complexity and the presence of an output schema, the description covers everything an agent needs: safety gate, input source, idempotency, asynchronous behavior, inside/outside close-run routing, link limitations, manual-upload fallback, and required reporting to the user. 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?

Schema description coverage is 100%, so the baseline is already high. The description adds meaningful parameter guidance by naming the source of counterparty_company_ids (well_list_missing_invoices) and explicitly noting the tool takes no period argument, which prevents a common misuse. It does not add much beyond schema for workspace_id, conversation_id, or idempotency_key, but those are already well described in the schema.

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

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

The description opens with a specific verb and resource: 'Queue invoice collection for named counterparties,' and adds a precise mechanism: 'one durable backlog task per counterparty.' It clearly distinguishes this tool from the close-run variant, well_enqueue_close_invoice_fetch, and positions it against well_preview_invoice_fetch.

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 exactly when to invoke the tool ('only after the user explicitly confirms the launch'), never on own initiative, and where the input comes from ('Get counterparty_company_ids from well_list_missing_invoices'). It explicitly routes to well_preview_invoice_fetch for read-only preview and to well_enqueue_close_invoice_fetch inside a close run, leaving no ambiguity about alternatives.

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

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

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful behavioral context beyond the annotations: it draws nothing on screen, asks for no confirmation, reports provenance and stored 'Suggested' fills, and cannot draw a confirmation card. This is exactly the kind of behavioral disclosure an agent needs to invoke the tool correctly.

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 carries useful decision-relevant information. The core behavior is front-loaded in the first sentence, and the warning about the confirmation-flow alternative is clearly separated. Minor redundancy between 'WITHOUT showing the user anything' and 'draws nothing on the user's screen' keeps it from 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 read-only settings tool, the description is complete: it states what is returned conceptually, explicitly clarifies the silent/no-UI behavior, gives conditional usage guidance, and distinguishes it from the sibling show tool. The output schema covers return-value details, so nothing essential 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 `workspace_id` and `conversation_id` thoroughly. The description does not add significant parameter-specific semantics beyond the schema, which merits the baseline score of 3.

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

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

The description states a specific verb ('Read'), resource ('the workspace's accounting settings and their provenance'), and importantly differentiates this from the sibling `well_show_accounting_settings` by emphasizing it does not draw anything on the user's screen. An agent can unambiguously identify what this tool does and what it does not do.

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: use this tool only for a silent CHECK the model acts on itself, and read fields and act in the same turn. It names the alternative `well_show_accounting_settings` for when the user must review or confirm, and explains why using this tool for a confirm step would leave the user with nothing to act on.

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 the tool as read-only and non-destructive, and the description goes beyond them by revealing that it draws nothing on screen, returns no card, and must be answered in the same turn. It also discloses a critical limitation: this tool cannot render a connect card, which materially changes how an agent should use 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 dense but every sentence earns its place: purpose is front-loaded, usage guidance is concrete, and the sibling-tool warning is prominent. The final paragraph deliberately avoids duplicating the field reference by pointing to well_list_connectors, keeping the description focused.

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 nine parameters and an output schema, the description covers the essential selection and invocation context: what this tool reports, when to call it, when to call the sibling instead, and the UI behavior the agent must account for. Since the schema fully documents parameters and an output schema exists, nothing critical is missing.

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

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

The input schema has 100% description coverage and individually documents all nine parameters in detail, so the description does not need to repeat parameter semantics. The description adds only a cross-reference to well_list_connectors for field-level definitions and mentions 'same scope arguments,' which is useful routing context but not new parameter meaning.

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

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

The description opens with a specific verb-resource pair: 'Read what a workspace has CONNECTED and what it can connect,' which is far more precise than the title alone. It also explicitly differentiates this tool from well_list_connectors by saying the connect step must call the sibling instead, and clarifies this tool is the answer for coverage checks.

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 cases: every coverage check, a data skill confirming a bank is connected, a step needing a workspace_connector_id, and a health read on a connector. It also gives explicit when-not-to-use guidance, including a direct instruction to call well_list_connectors for connect steps and a warning not to read workspace_connectors records manually.

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 read as safe; the description adds meaningful behavioral context beyond that: the meaning of absent customer_kind, the semantics of fields entries with no value, that unstorable_fields are not user-closable gaps, and that the read will not guess a workspace when multiple are authorized. 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 long but densely structured: purpose, usage boundary, return shape, edge-case semantics, and workspace guidance each earn their place. It is front-loaded with the core identity statement. Slightly more verbose than strictly necessary, but every sentence adds actionable 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 read-only single-resource tool with an output schema and rich parameter schema, the description is complete. It explains how to interpret ambiguous return states, when to call directly, when to pass workspace_id, and how to distinguish from the relevant sibling. Nothing needed to invoke 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 coverage is 100%, so the schema already documents company_id, workspace_id, and conversation_id fully. The description adds some parameter-level context, especially the workspace_id rule for multi-workspace tokens, but most of its added value concerns output interpretation rather than parameter meaning.

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

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

States a precise verb and resource: 'Get one CUSTOMER's e-invoicing identity' and defines the object as the registry values an invoice is routed on or a period aggregate is reported under. It also differentiates itself from well_get_own_company by scoping to the party the workspace bills, so an agent can distinguish it from siblings without opening schemas.

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 examples ('can we invoice this customer electronically', 'what is their SIREN / VAT number') and explicitly routes the alternative case to well_get_own_company. It also provides conditional call guidance for single-workspace versus multi-workspace tokens, leaving little 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 and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it describes the return object's structure (colors, series, shape, fonts, color_scheme), explains how to interpret the absence of color_scheme, and notes that values come from the token package and cannot drift. It also clarifies that omitting workspace_id returns the same answer, which is a behavioral nuance beyond the schema. No contradictions 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 moderately long but every sentence earns its place. It front-loads the core purpose and then delivers usage constraints, return-value semantics, and a final note on provenance. While it could be trimmed slightly (e.g., the last sentence on token drift is somewhat tangential), it remains well-structured and efficient without redundancy.

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

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

For a read-only tool with two optional parameters and a rich return object, the description is complete. It explains when to use it, when not to, what the return object contains and how to interpret it, and covers the edge case of missing color_scheme. The presence of an output schema reduces the need to detail return formats, and the description provides the semantic guidance needed for correct invocation. Nothing critical is missing.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description adds one meaningful clarification beyond the schema: it explicitly states that omitting workspace_id returns the same answer because tokens describe the package, not workspace data. This is valuable extra semantic info, so a score of 4 is justified over the baseline 3.

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

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

The description clearly states the tool's purpose: 'Get Well's colours, shape and type vocabulary' with the explicit goal of making composed views look like Well. It distinguishes itself from all siblings by being the only tool about design tokens, and it specifies the exact resource (colours, shape, type) with a concrete verb 'Get'.

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 comprehensive. It states the condition 'Call this ONLY when you are about to render something yourself' and provides clear exclusions: 'You do not need it to answer in prose or in a markdown table' and 'Do NOT use it to restyle a card a Well tool already drew.' It also references the alternative (host-rendered cards) and explains why a second styled copy is a duplicate. This is model 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 as read-only and non-destructive, and the description adds meaningful behavioral detail beyond that: it caps child collections at 50 rows, excludes aggregates, stops at depth 3, and warns that depth 3 produces a LARGER payload. It also discloses that it resolves field paths automatically rather than requiring the caller to specify them, which is important 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?

The description is organized into a clear purpose statement, a convenience rationale, and a bullet-like depth breakdown. Every section earns its place, and the most important scoping and limit information is front-loaded while the alternatives are clearly appended.

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 tool's scope, limits, exclusions, depth semantics, and the appropriate fallback for pagination, which is everything an agent needs to decide whether and how to call it. The output schema exists, so return-value detail is not required from the description, and annotations already cover the safety profile.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches the depth parameter substantially by defining exactly what level 1, 2, and 3 return and the 50-row cap. It does not add much to id/root/workspace_id/conversation_id beyond the schema, but the depth semantics alone justify a point above baseline.

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

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

The description opens with 'Read ONE entity with its sub-resources nested in a single call', naming the exact verb, resource scope, and call shape. It also distinguishes itself from well_get_schema + well_query_records, so an agent can immediately tell this is the convenience read tool for a single entity graph.

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 itself as a convenience over well_get_schema + well_query_records and explains that it resolves field paths for you. It also gives depth-level guidance and directs users to well_query_records when they need a full list or to page a large child collection, making the alternative selection 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 already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat that. It adds valuable context: the tool is read-only (stated), the text result reports only counts (not node listings), and the at_company_cap behavior is disclosed. This goes beyond annotations to explain how to interpret results, which is critical for correct agent 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?

The description is well-structured: first sentence defines the tool's core purpose, followed by usage conditions, then guidance on interpreting results, and finally a clear read-only statement. It's front-loaded with the most important info and every sentence earns its place. No fluff or redundancy.

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

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

Given the tool has an output schema, the description doesn't need to detail return values. It covers the key aspects: what the tool does, when to use it, how to adjust output via parameters, how to interpret results (counts vs graph), and the at_company_cap edge case. The parameters are well-documented in the schema, and the description fills the behavioral gaps. For a visualization tool, 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 100%, so parameters are fully documented in the schema. The description adds context on how to use them (e.g., 'thin a dense workspace to its hubs' for min_degree, 'narrow the drawing' for perspective), but this is complementary rather than essential. For a tool with 6 well-described params, the baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool draws the workspace's context graph (companies, people, accounts, etc.) and visualizes connections. It distinguishes itself from siblings like well_get_entity or well_search_context by focusing on the graph visualization. The verb 'draw' and resource 'context graph' are specific and unambiguous.

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

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

It explicitly states when to use: when someone asks to see how business data connects or wants a picture of the workspace. It also lists narrowing parameters (perspective, time_window, min_degree, company_cap) and provides behavioral guidance on what to say when at_company_cap is true. It implies when not to use (e.g., for specific entity details) by contrasting with the graph's scope.

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

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

Annotations already mark the tool read-only and non-destructive, and the description adds the valuable behavioral guarantee that holdings are 'fetched fresh from Plaid on every call (never stored/stale data).' It also discloses the product constraint (only Plaid connectors supporting the investments product) and what the tool is not for, with no contradiction to annotations.

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

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

The description is front-loaded with the core purpose, then uses a labeled WORKFLOW and explicit exclusions. Every sentence earns its place; the length is justified by the routing decisions an agent must make and there is no filler or repetition.

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

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

Given the annotations, a full output schema, and detailed parameter descriptions, the description supplies the essential missing workflow glue: how to obtain the workspace_connector_id, which sibling tools are not the right ones, and where to go for investment transactions. Nothing critical is missing for correct invocation.

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

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

The schema already documents all three parameters in detail (100% coverage), so the baseline is 3. The description adds extra operational meaning beyond the schema by telling the agent to pick the connector with connection_status 'enabled' and to read workspace_connector_id 'directly off the row,' which is useful parameter-filling guidance not present in the schema.

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

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

The description opens with a concrete verb and resource: 'Get the live holdings/positions (what's currently held and its value) for a connected Plaid investment account.' It also differentiates itself from connector passthrough tools and investment-transaction queries, so an agent can distinguish it from siblings like well_list_connector_tools and well_query_records.

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

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

The WORKFLOW section gives an explicit two-step recipe: call well_list_connectors, select only the ENABLED Plaid connector, read workspace_connector_id, then call this tool. It further states exclusions ('not the MCP-transport connector-tool-passthrough tools', 'not for investment transactions') and names well_query_records for transactions, making when-to-use and when-not-to-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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavior beyond that: `anchor: null` means no confirmed own company, candidates must not be promoted to anchor, registry tax ids and addresses are intentionally omitted, and this read draws no UI. 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 but front-loaded with the core behavior and each block earns its place: the mine-vs-theirs usage rule, the explicit alternative routing, the null-anchor handling, and the withheld-fields disclosure. The warning callout for `well_show_company_candidates` is particularly well placed.

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 an output schema and safety annotations, the description covers everything an agent needs: what the two outputs mean, how to handle null anchor, what is not returned, and how to route interactive candidate selection to a sibling. 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?

Schema description coverage is 100%, so the schema already documents both parameters fully. The description adds scoping context ('read from the same workspace this call is scoped to') but no parameter syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get which company the workspace itself is', and concretely defines the two outputs (`anchor` and `candidates`). It explicitly distinguishes itself from the sibling `well_show_company_candidates`, so an agent can tell them apart without inspecting schemas.

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

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

It gives clear when-to-use guidance ('whenever a question turns on "mine" versus "theirs"'), an explicit anti-pattern (never filter by company NAME), and names the alternative to use instead for interactive selection (`well_show_company_candidates`). It also states no prerequisite call is needed.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds real behavioral context beyond that: the shape of returned entries (path, type, context, enrichment), how field type constrains whereClause operators, and that workspace_id is optional because this tool describes the token itself rather than a workspace's data. This materially enriches what the annotations alone 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 longer than average, but it is well organized into USAGE, WORKFLOW, and return-format sections with front-loaded purpose. A small amount of repetition exists around operator guidance and path conversion, but each major block earns its place.

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

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

For an introspection tool with an output schema, 100% parameter coverage, and safe read-only annotations, the description is complete: it covers invocation patterns, a canonical example, the expected workflow before querying, and the meaning of returned fields. Nothing needed 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?

Since schema coverage is 100%, the baseline is 3, and the schema already documents root, depth, workspace_id, and conversation_id. The description adds value beyond the schema by explaining operator rules per type (enum uses ONLY _eq, _neq, _in, _nin, _is_null) and by giving the path-to-array conversion rule for well_query_records. That lifts it above baseline.

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

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

The first line, 'Discover available data types and fields,' states a specific verb and resource. The usage examples clearly distinguish the no-argument call (list all roots) from the root-specific call (list fields), and the workflow explicitly routes the agent onward to well_query_records, making the introspection role unmistakable relative to sibling tools.

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

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

The description gives explicit call order: call well_get_schema() first to see roots, then with a root to see fields, and then call well_query_records. It also calls out the accounting-graph roots for financial statements. It does not explicitly discuss when not to use this tool versus well_get_entity or well_get_graph, so it stops short of the highest bar.

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

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

The description discloses a state-changing behavior: passing mark: true advances the read cursor and clears the app's unread state. This contradicts the annotations' readOnlyHint: true, which implies no mutation. Per the rubric, a description that contradicts annotations earns a 1 even though the disclosure itself is detailed.

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 and usage, then organized into clear sections for return fields, null semantics, skills, suggested steps, mark behavior, and workspace selection. It could be tightened by trimming some output-field explanation that may duplicate the output schema, but each section earns its place given the tool's complexity.

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

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

For a 3-parameter tool with 100% schema coverage and an output schema, the description is exhaustive: it covers call routing, mark side effects, workspace disambiguation, null/unknown semantics, truncation, roster failures, suggested-step ordering, and the rule to state figures as returned. Nothing operational needed to call or interpret the tool 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%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: mark advances the cursor and is shared with the app, false means inspect-only, and workspace_id should be passed when the token authorizes multiple workspaces because the tool will not guess. This exceeds the schema's 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 states a specific verb and resource: it returns everything a returning person's first answer needs, including workspace activity, current state, and relevant Well skills. It also distinguishes itself from related tools by naming the signing-back skill workflow and well_search_skill, so an agent can tell this tool apart from its 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-call and when-not-to-call guidance: for catch-up requests it says load the signing-back skill first instead, and direct calls are reserved for when a loaded skill says so or when the person only wants raw counts. It also explains mark true/false semantics and workspace_id requirements for 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?

Annotations already mark this read-only and non-destructive, and the description adds meaningful behavioral context beyond that: the tool returns exactly one markdown document, the content is mandatory instruction, and the returned document may direct the agent to invoke other Well skills. This is a clear behavioral contract, not a paraphrase of the annotations.

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

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

The description is front-loaded with the core purpose, and every subsequent sentence earns its place: return format, instructional nature, sub-skill loading, search-first guidance, and no re-fetching. It is substantive without being 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?

Given the output schema and annotations, the description covers everything an agent needs to call this tool correctly: what it returns, how to use it, when to search first, and why repeated fetches are wasteful. The conversation_id and workspace_id behaviors are fully documented in the schema, 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?

Schema description coverage is 100%, so the baseline is 3 and the schema already documents skill, workspace_id, and conversation_id. The description adds some practical context around the id and the fixed catalog, but it does not meaningfully enrich the parameter semantics beyond the schema.

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

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

The description opens with a specific verb and resource: get the Well procedure for a job. It clearly distinguishes this from well_search_skill by framing search as the precursor for obtaining an id, and it states that the tool returns instructional markdown, not background material.

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 guidance: use well_search_skill first when you lack the id, load referenced skills at the moment the document says, and do not re-fetch a document you already hold because the catalog is fixed. It also tells the agent to follow the retrieved procedure exactly, which removes ambiguity about how to act on the result.

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 say readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'This tool reads only — it changes nothing.' It goes further by disclosing important runtime behavior: 'not_found_yet' is not an error, null counts mean unknown rather than zero, and 'records' contains only minted transactions. These details materially shape how an agent interprets results.

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: core purpose, call cadence, status semantics, null handling, records scope, and read-only guarantee. The bullet list for statuses makes the dense information scannable, and the most important usage instruction is front-loaded before the status 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?

For a polling/query tool with three parameters, strong annotations, and an output schema, the description covers everything an agent needs: when to call, what each status means, how to interpret nulls, what records contain, and that the operation is side-effect free. Even without the output schema, the description would be almost sufficient.

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

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

Input schema coverage is 100%, so the schema already fully documents document_id, workspace_id, and conversation_id. The description adds contextual value by tying document_id to the value returned by well_create_statement_upload, but it does not add meaning beyond what the parameter descriptions already provide. 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: 'Read the outcome of a bank-statement upload started with well_create_statement_upload, by the document_id that tool returned.' It clearly separates this read tool from its creation counterpart by stating it does not create or redraw the card. No agent could mistake it for the upload or create tools in the sibling list.

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 call timing: 'Call it once, shortly after the client has uploaded the file bytes' and explains when not to call again: 'The card polls this import result itself until it settles, so call this tool again only if the user asks.' It also treats 'not_found_yet' as a normal early state and instructs to poll again after upload. This is strong, actionable usage guidance.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds substantial behavioral context beyond that: it does not draw a card, open: false means settled, success: false means UNKNOWN with open absent, two worklists return count, and counterparties_to_categorize pays for month spend twice. No contradiction with annotations appears.

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

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

The description is long but well-organized with bold section headers and front-loaded key guidance. Nearly every sentence contributes, though there is some repetition (e.g., 'a picker with no rows and a dead button' appears twice) and a few rhetorical asides that could be tightened 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?

Despite having an output schema, the description covers everything an agent needs to call this correctly: the exact gate semantics, ordering dependencies, scope requirements, failure behavior, cost implications, workspace resolution, and conversation_id propagation. It is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by mapping each worklist to its required scope fields, stating that omitted required scope causes a refusal, and clarifying workspace_id and conversation_id handling. It reinforces and extends the schema without replacing it.

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

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

The description opens with a specific, unambiguous statement: 'Ask whether a repair gate is still OPEN, without drawing its card.' It names the exact resource (repair gate/worklist status) and clearly distinguishes itself from the worklist-read siblings by framing it as a predicate check. It also enumerates the worklists it covers and contrasts with the reads that draw cards.

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 sequencing guidance: call this BEFORE the worklist read when checking rather than repairing, and only call the worklist read when this returns open: true. It also names alternatives like well_list_connectors and well_list_counterparties, specifies workspace_id behavior for multi-workspace tokens, and gives retry/stop instructions on failure. This is unusually strong usage guidance.

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

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

The description goes well beyond the readOnly/destructive hints by detailing side effects: invitations can be sent, reissued, or refused; an invitation may persist without its email; and permission failures surface as INSUFFICIENT_PERMISSIONS. This is exactly the behavioral context needed for a mutating tool.

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

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

The description is dense but organized into purpose, input, output, and permission/edge-case paragraphs. Code-formatted parameter names and the front-loaded primary use keep it scannable, and every sentence carries actionable 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 with two target kinds and nuanced email behavior, the description covers return statuses, refusal reasons, permission failure, the active-member prohibition, and the delayed-email flow. The output schema and parameter descriptions cover the remainder.

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 workflow meaning on top: the 1–20 invites shape, workspace vs group targets, the notify:false use case, and how to reuse the returned person_id to assign an owner.

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 action and resource: inviting teammates into a workspace or workspace group. It is immediately distinguishable from surrounding read/search tools like well_list_member_candidates.

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 sequences the tool after well_list_member_candidates and states when not to invite (address already active). It also gives the permission precondition (owner/admin only) and the notify:false assign-then-invite flow.

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

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

Annotations already mark the tool as non-read-only, open-world, and potentially destructive. The description adds useful behavioral context: it can either mutate provider data or read unsynced content, returns the provider result or { success: false, error } on failure/grant denial, and invalid workspace_connector_ids fail server-side. This meaningfully goes beyond annotation coverage.

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 well-organized: clear purpose, explicit exclusion, numbered workflow, and a concise constraint paragraph. It is front-loaded with the core action and the 'NOT' condition. Minor redundancy (MCP/enabled requirements repeated) prevents a 5, but every sentence adds selection or invocation value.

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 (6 parameters, nested objects, output schema present), the description covers the essential call path (workspace_connector_id, tool, args) and the prerequisite discovery steps. It explains error behavior and the boundary of supported connectors. The optional parameters (workspace_id, conversation_id, idempotency_key) are fully documented in the schema, so the agent has enough to invoke correctly.

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

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

Schema coverage is 100% and each parameter already has a thorough description. The tool description adds valuable workflow semantics: the 'tool' parameter must be one of the names from well_list_connector_tools and 'args' must conform to that tool's live input schema, which is not fully stated in the schema itself. This elevates the score above baseline 3.

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

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

Description states a specific verb and resource ('Run one tool on a connected provider's own MCP server') and gives concrete examples (create a record in Attio, read unsynced docs/CRM content). It explicitly contrasts with well_query_records for financial data, making sibling differentiation immediate and clear.

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

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

Provides explicit when-to-use (actions user asked to take, reads of content Well does not sync) and when-not-to-use (financial data, routed to well_query_records instead). Includes a numbered workflow naming prerequisite tools (well_list_connectors, well_list_connector_tools) and states the connection must be enabled and expose an MCP server.

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/destructiveHint annotations, the description discloses numerous behavioral traits: it applies no scope, no type filter, no amount selection, and no currency conversion. It explains partial reads, unreadable_rows, null balance meanings, verification_rejected, duplicate handling, and the months_back series, all of which materially affect the output. No contradiction exists 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 front-loaded with the core purpose and then organized into clear thematic paragraphs (scope, type, amount, currency, duplicates, nulls, partial reads, months_back, workspace). It is long, but each paragraph earns its place by addressing a distinct misinterpretation an agent could make; only slight trimming could improve it.

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 this much behavioral nuance, the description is remarkably complete: it covers ownership rules, account type implications, amount selection, currency conversion, duplicates, null semantics, partial reads, unreadable_rows, and workspace selection. Since an output schema exists, the description doesn't need to explain return fields, and every call-relevant aspect is addressed.

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

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

Input schema covers 100% of parameters, so baseline is 3. The description adds semantic depth: it explains that months_back is a second query that returns one reading per complete month end, that workspace_id must be passed when multiple workspaces are authorized, and that conversation_id must be passed back on every call. This goes beyond the schema descriptions.

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

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

The opening sentence states a specific verb and resource: 'List every account on the workspace with its stored balance.' It immediately distinguishes itself from rendering tools by saying 'Rows only — this tool holds no definition of cash, and returns no figure the app renders,' which separates it from siblings like well_render_cash_position and well_render_cash_forecast.

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

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

It explicitly instructs when to use this tool: 'Use it when you are computing a cash figure whose RULES you are stating yourself...' and routes to well_render_cash_position or well_render_cash_forecast for presentation. It also clarifies the relationship with well_sum_transactions and explains workspace authorization conditions, so an agent knows exactly how to choose it over alternatives.

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

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

Well beyond the annotations (readOnlyHint=true), the description discloses that the tool draws its card on EVERY call including the empty one, that success:false means the worklist state is UNKNOWN rather than empty, and that truncated:true makes a count a floor rather than a total. It also documents field semantics such as company_suggestion being ABSENT meaning no grounded guess existed — not that the row was checked and found ownerless — which prevents serious misuse.

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

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

The description is well-structured with bold-led paragraphs and a strong front-loaded purpose, and nearly every paragraph carries a distinct operational rule. However, it runs to roughly 600 words for a read-only list tool with four documented parameters; sections like 'The second is not the lesser case' and repeated warnings against guessing an owner could be tightened without losing substance.

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 domain's subtlety — ownership semantics, the unknown-vs-empty trap, and the relationship to well_sum_transactions — the description covers everything needed: the two states, own_company_id's anchoring role, company_suggestion presence/absence rules, success/truncated meanings, the lighter-weight sibling, and workspace disambiguation. The output schema and full parameter coverage handle returns and syntax, leaving no operational gap for an agent to guess about.

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 operational context beyond the schema: companies offered alongside rows are capped and company_search exists to narrow them rather than assuming the card carries every company. workspace_id is also motivated as an answer to 'this read will not guess which one you mean,' which gives meaning beyond the schema's literal text.

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 and resource — 'List the workspace's accounts that cannot yet be placed on either side of a transfer' — and explicitly defines the two qualifying states (no company attached; ownership unknown). Frames the result as a gate on a FIGURE rather than a tidiness list, which differentiates it from the many list siblings and clarifies what the list is for.

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 routes between this tool and well_get_worklist_status: call this directly when the user asks to see/list/fix these rows, but call the status tool first when the agent only needs to check whether work remains, and call this only after status answers open: true. Also gives conditional workspace guidance — call directly with a single-workspace token, pass workspace_id when the token authorizes several.

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

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

Goes well beyond the readOnly/destructive annotations by disclosing important behavior: categories with no outflow are omitted, from is inclusive and to exclusive, partial means nothing was measured, currency mixing is refused, internal transfers are excluded, and the direction convention is elected once over the whole window. Also reveals that records are scoped to the conversation. No annotation contradiction 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 long, but the length is mostly earned by the tool's complex refusal and edge-case behavior. It is front-loaded with purpose and output shape and uses paragraph-per-topic structure; it loses a point because some caveats, particularly currency and unclassified amounts, are stated more verbosely than needed.

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 return fields, all major refusal branches, multi-workspace behavior, conversation scoping, and the downstream workflow with sibling tools. Despite the long description, nothing an agent needs in order to call this tool correctly appears 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%, so the baseline is 3, but the description adds real operational meaning: convention must match the burn election and magnitude/mixed windows are refused, window boundaries are reinforced, and workspace_id is required when multiple workspaces are authorized. It does not add significant new meaning for conversation_id beyond what the schema states, so it is not a 5.

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?

Opens with a specific verb and resource: 'List the categories a reader can exempt from burn over one window.' It immediately scopes the tool as the exemption-card view and explicitly says it 'measures nothing the sum did not already measure,' which distinguishes it from related sum/render 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?

Provides explicit context: call directly for a single-workspace token, pass workspace_id for multiple workspaces, and reuse the returned keys with well_switch_workspace, well_wait_for_selection, and well_sum_transactions. It gives a clear workflow, but it does not explicitly state when-not to use this tool versus a specific sibling, stopping short of a 5.

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

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

Annotations only declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: sorting by largest holdings, omitting zero-count types, ownership filtering, excluded_not_owned, unsettled_ownership, unreadable_balances, unreadable_currency, folded_duplicates, partial:true semantics, and the meaning of an empty selection. This far exceeds the annotation baseline.

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 it is organized into purposeful paragraphs covering distinct edge cases, and the core purpose is front-loaded. Some imperative phrasing is slightly repetitive ('Say it', 'state them', 'keep them apart'), so it is not maximally concise, but every section contributes operational guidance.

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, the description does not need to restate return values. It covers workspace authorization, conversation continuation, the selection-wait contract, empty-selection resolution, follow-up rendering, and all output caveats. Nothing needed for correct invocation 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 baseline is 3. The description reinforces the workspace_id rule and the conversation_id requirement, but it mainly restates what the schema already documents rather than adding genuinely new parameter-level meaning.

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

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

The description opens with a specific verb and resource: 'List the account types a reader can count as cash, each with what it holds.' It also distinguishes itself from well_list_account_balances by clarifying it 'measures nothing' that tool did not already read, giving the agent a clear basis for selection.

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

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

The description gives explicit workflow guidance: call directly when the token authorizes one workspace, pass workspace_id when it authorizes several, call well_wait_for_selection in the SAME turn, and then apply the selection and call well_render_cash_position. It also states when no wait is needed, making the usage conditions unambiguous.

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

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

Annotations already mark the tool readOnly and non-destructive, so the bar is lower; the description adds critical behavior beyond those hints: 'This tool draws its card on EVERY call, the empty one included', it waits on the turn that drew it, and it explains status semantics like to_configure/disabled and the server-side resolution of 'degraded'. This materially changes how an agent should sequence calls.

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 it is front-loaded with the highest-stakes warnings (card rendering, silent alternative, wait protocol) and organized into scoping, paging, per-field, and top-level-field sections. Some admonitions repeat, so it is not a model of brevity, but nearly every sentence carries operational weight given the tool's complexity.

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

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

For a tool with 11 optional parameters, complex connection-status semantics, top-level fields, paging behavior, and sibling interactions, the description is exhaustive: every status, null case, scope, and edge condition is covered. An agent has enough to call it correctly and interpret the result without external knowledge.

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, but the description adds flow-level meaning beyond the schema: from_selection is the step that FOLLOWS a vendor pick, country reorders but never drops rows, kind: storage is the output direction versus upload_surface, and include_unsent_counts exposes the whole backlog independent of the page. These are not inferable from the parameter names alone.

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: 'List the connectors a workspace can install AND everything it has already connected, each with a one-click install deep link.' It names the card-drawing side effect and distinguishes itself from well_get_connector_coverage and well_list_connector_tools, so an agent can tell it apart without opening schemas.

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

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

Explicitly states when to use this tool versus alternatives: 'Do NOT read workspace_connectors records to work out connection coverage; this tool is that answer', routes silent checks to well_get_connector_coverage, vendor-pick probes to well_get_worklist_status, and live-connection actions to well_list_connector_tools. It also instructs the agent to call well_wait_for_selection in the turn that drew the card.

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