Well

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

Annotations only declare a non-read-only, non-destructive, closed-world write. The description adds substantial context: refusals are atomic ('nothing written'), phone is unsupported on a company and errors clearly, a leading '+' is normalized onto phone numbers, label/platform default to 'work'/'website', and the draft/registry guardrails are spelled out. This is precisely the behavior an agent needs before attempting the write.

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?

Purpose is front-loaded and the bulleted channel mapping is scannable and waste-free. The draft_party paragraph is a dense multi-clause sentence that partly restates the schema's own description of that parameter, costing some readability without adding much new 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 10-parameter tool with nested objects and an output schema, the description covers every decision point an agent faces: which value fields to fill per channel, when registry_ref or draft_party applies, the unsupported company-phone combination, and where to go to read. Return values are covered by the output schema, so no gap remains.

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 field meanings and defaults. The description still adds value by presenting the channel→value-field mapping as a compact contract and by disclosing the automatic '+' prefixing for E.164 numbers, which the schema does not mention. It largely mirrors the schema for label/platform defaults, so it sits just above the baseline rather than far above 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?

Opening sentence gives a specific verb and resource ('Add a contact channel to a company or person') and is immediately followed by the exact REST endpoints it wraps. It also differentiates from siblings by naming well_query_records as the tool for reading existing channels.

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?

Goes well beyond naming alternatives: it specifies when to pass registry_ref (only for an address read from a registry hit), when to pass draft_party ('receiver' vs 'issuer' on an invoice draft), and the exact refusal conditions for each. It also states the fallback rule for ambiguous draft conversations ('ask them in one line first') and routes reads to well_query_records.

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

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

Goes far beyond the annotations by disclosing the re-validation of the address on every request, the idempotent behaviour ('adding the same address again returns the same connector'), and the failure taxonomy with literal codes (sign_in_not_open, sign_in_on_another_domain, sign_in_owner_unverified). It also states the credential constraint ('never ask for a key, a token or a password') and that an api_key is added outside the conversation, which is exactly the kind of operational context annotations cannot 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?

Long but front-loaded: identity of the connector, then preconditions, then server-side checks, then outcome handling. Nearly every sentence carries an operational rule, though the outcome-by-outcome reply script makes it heavier than strictly needed for tool selection.

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 tool with open-world network access and multiple failure modes, the description covers permissions, pre-checks, idempotency, partial-success states and refusal wording. Even though an output schema exists (so outcome fields needn't be re-explained), the outcome-handling guidance adds useful agent behaviour rather than duplicating 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 description coverage is 100% and each parameter already carries detailed prose, so the schema does the heavy lifting. The description only reinforces that url and name come verbatim from the person and that no credential parameter exists; it adds little per-parameter meaning beyond that. 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 a specific verb, resource and scope: 'Save the MCP server of a tool Well's catalog does not carry as a connector of this workspace.' It immediately distinguishes itself from catalog-based siblings (well_request_connector, well_show_connector_request, well_update_custom_connector) by both what it creates and who sees it.

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

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

Gives explicit preconditions and the exact predecessor tools with their required return values ('only when well_show_connector_request returned can_add_self: true', 'after well_probe_mcp_server answered mcp_server'), plus the authorization gate (owner or admin, others refused). An agent knows precisely when to call it and when not to.

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 far beyond the annotations: user confirmation on a card before rows are added, a 20000-row scan ceiling, a race window when two calls hit the same sheet, connection-owner-only writes, and the full outcome vocabulary (already_logged, too_many_rows_to_check, not_connection_owner, connection_choice_needed, needs_reconnect, unconfirmed) with the follow-up action for each. This is exactly the kind of operational context annotations cannot carry.

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?

Purpose and the write-restriction caveat are front-loaded, and the dense paragraphs each carry non-obvious behavior. Some trimming is possible: rows_appended/rows_skipped and the outcome codes are partly restated despite an output schema, and the closing line says 'this read will not guess', which reads like it was copied from a read tool and briefly muddies the write framing.

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 8-parameter open-world write with an output schema, the description covers what an agent needs to call it correctly: creation semantics, dedup strategy, hard limits, authorization failures, retry guidance ('never repeat a call that returned appended'), and multi-workspace routing. 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 coverage is 100%, so baseline is 3, but the description adds real meaning: each cell is stored as typed and a leading '=' stays text, key_column deduplicates against the sheet column and within a single call, and sheet_name creates the sheet on first use with a new name. It also explains the workspace_id/workspace_connector_id branch, though conversation_id and idempotency_key are left to 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 verb and resource ('Add rows at the end of a log sheet'), plus the exact scope: a sheet Well keeps in the Well folder of the connected Drive. That distinguishes it from siblings like well_save_file_to_drive or well_export_rows_as_file without the agent needing to open a 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?

Gives an explicit trigger ('when the user asks to log, record or add rows to a Google Sheet') and an explicit exclusion with a fallback ('Well cannot write to a sheet the user made or picked: say so and offer a Well log sheet instead'). It also states when to pass key_column versus not, and that no workspace call is needed first when the token authorizes one workspace.

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 flag destructiveHint=true, but the description goes far beyond that: it explains the downstream accounting consequence (internal-transfer rule removes spend from burn, silently, with no error) and that a cross-workspace company_id is refused rather than resolved. It even discloses the success return shape, which is unusually complete for a write 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?

Well front-loaded: purpose, then activation condition, then the cross-field requirement, then the enum glossary, then the consequence. Some prose is rhetorically padded ('quietly and consistently, with no error anywhere'), but nothing is redundant enough to obscure the call.

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

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

For a 7-parameter destructive write with an output schema, the description covers purpose, preconditions, the risky semantics and the return value. Session parameters (conversation_id, workspace_id, idempotency_key, workspace_scope) are fully documented in the schema, so their absence from the description is not a gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by adding a constraint the schema does not encode (at least one of company_id or ownership must be supplied, while the schema only requires account_id), semantic explanations for each ownership value, and the `company_id: null` detach behaviour.

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, resource and effect: 'Attach a bank account to a company, and say whether the workspace owns it.' That distinguishes it from neighbouring tools like well_bind_statement_account and well_list_accounts_needing_company, which an agent can rule out from this sentence alone.

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 an explicit activation condition — accounts with no company, or ownership still `unknown` — and an explicit restraint: do not infer ownership from name, bank or co-occurring company; ask or leave `unknown`. That is when-to-use plus when-not-to-guess, which is exactly the guidance a figure-affecting mutation needs.

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 far beyond the annotations (readOnlyHint=false, destructiveHint=true) by disclosing replace semantics ('anyone not sent is removed'), the empty-array-clears behavior, the fan-out rule (one proof task per distinct person, one invoice resolving all), and three specific refusal reasons (NOT_FOUND, CLOSE_OWNER_PERIOD_FROZEN) with batch-level failure behavior. This is exactly the destructive-operation context the annotations alone cannot 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?

Front-loads the required parameters and core semantics before the behavioral detail, and each section (required inputs, set semantics, refusal behavior) is discrete. It is on the longer side and uses heavy capitalization emphasis, but the length is justified by the destructive batch-write complexity.

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

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

With an output schema present, return values need no explanation, and the description fully covers the write's replace semantics, fan-out consequences, refusal modes, and the instruction to surface the fan-out to the user. Nothing needed to invoke this destructive batch tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: the SET-not-single-owner nature of owner_person_ids, the per-transaction scoping, and the requirement that person_ids already be workspace members. Some of this (empty array clears owners) duplicates the schema, but the set semantics go beyond it.

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

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

States a specific verb and resource ('Set the owner SET of the missing-invoice TRANSACTIONS you name') and immediately differentiates it from siblings by declaring it 'the only write for missing-invoice ownership'. An agent can distinguish it from well_list_missing_invoice_owners and well_list_missing_invoices without opening any schema.

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

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

It names where inputs come from ('from well_list_missing_invoice_owners') and how to obtain people ('get them with well_query_records on people'), which routes the agent to the right siblings. It does not state an explicit when-not condition, but the 'only write for missing-invoice ownership' framing makes the usage context clear.

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

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

Annotations only give the flag profile (writes, idempotent, not destructive, closed-world). The description adds substantive behavior: nothing is re-read or re-uploaded, per-status post-conditions (`imported`/`needs_account`/`duplicate`/`skipped`/`failed`), that `success: false` means nothing was written, and what the errors mean.

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 opening sentence with the routing and guardrails following in clear bulleted blocks. It is long, and the status enumeration partly restates what the output schema already carries, which is the only real waste.

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 8 parameters, an output schema, and existing annotations, everything an agent needs is present: when to call, which parameter path to choose, what the member's answer implies for consent, how to read each returned status, and what a failure guarantees.

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 earns the extra point by supplying the 'exactly one of account_id / account_number / iban' constraint that the flat schema does not encode, plus the find-or-create semantics for `account_number` and `iban`. It says nothing about `workspace_id`, `conversation_id`, or `idempotency_key`, but the schema already documents those.

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 ('Bind a bank statement ... to the account the member picked, then import the lines') and scopes it to statements in `needs_account`. This clearly separates it from siblings like well_get_statement_import_result, well_upload_statement_content, and well_assign_account.

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?

Explicit preconditions ('Call it only after the member picked an account or typed its number'), explicit exclusions ('never call it for a statement that is not needs_account', 'never pick an account yourself'), and a routing decision between the three alternative parameter paths keyed to IBAN vs non-IBAN banks.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real signal beyond that: a hard cap of 20 results, the matching dimensions, the returned representation (read_page lines with refs), and a staleness warning with the corrective action. It does not cover zero-match behavior or whether the call waits for page load, which keeps it off a 5.

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

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

Three sentences, front-loaded with what the tool returns and how, followed by the execution context and ref lifecycle. Every sentence carries information, though the parenthetical about the single connected browser is slightly wordier 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?

With an output schema available, the description need not explain return values, and it still summarizes the return format helpfully. It covers target selection, matching, result limits and ref staleness — the main things an agent needs. Minor gaps remain around empty results and page-load behavior, but nothing that would cause a misinvocation.

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 80%, so the schema already documents tab_id, workspace_id, conversation_id and workspace_scope. The description's only semantic contribution is clarifying that the query matches on role, name or value — useful, but it says nothing about the non-query parameters. 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 a specific verb (find), a specific resource (elements in a browser page), the match semantics (role, name or value), the result cap (up to 20), and the output shape (read_page lines with refs). An agent can distinguish this from well_browser_read_page and well_browser_get_page_text without opening any schema.

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

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

Establishes the operating context clearly: it runs in the Well tab group chosen via well_select_browser (or the sole connected browser), and it explains the ref lifecycle — refs come from read_page or find and go stale when the page changes, so re-read first. What is missing is an explicit statement of when to prefer find over read_page or get_page_text rather than issuing a full page read.

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 destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the mutation profile is known. The description adds genuinely non-obvious behaviour: a hard security carve-out for sensitive field types, the fact that it operates on the caller's own Chrome tab group, and that refs go stale on page change and must be re-read. It does not describe failure modes or what a successful set returns, which the output schema partly covers.

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

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

Four short sentences, front-loaded with the action and the security exclusion before the environment and ref-lifecycle details. Phrasing is telegraphic in places ('read again then') but nothing is redundant.

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

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

For a 7-parameter, nested-object mutation tool with an output schema, the description covers the operation, the sensitive-field exclusion, the sibling alternative, browser targeting and ref staleness. Remaining gaps — error behaviour and select value semantics — are modest given the rich schema and existing output schema.

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

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

Schema coverage is 86%, so the baseline is 3 and the schema already documents tab_id, workspace_id, conversation_id, idempotency_key and workspace_scope. The description adds real meaning for target.ref — where refs come from and when they expire — which the schema does not say, but it says nothing extra about value semantics for selects (e.g. option label vs underlying value).

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

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

The first sentence gives a concrete verb and resource ('Set a text field or a select of the ref to a value'), which is far more specific than the title 'Set a field'. It explicitly carves out checkbox/radio in favour of well_browser_left_click, but never mentions the sibling well_browser_type, so the boundary between 'set' and 'type' is left for the agent to guess.

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

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

It states when-not (password, card and code fields are never set), which alternative to use for other control types (well_browser_left_click for checkbox/radio), and the prerequisite for obtaining a usable ref (well_browser_read_page or well_browser_find, re-read after page changes). It also says which browser/tab group the call acts in and how that is chosen via well_select_browser.

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 cover read-only, non-destructive and open-world behavior, so the description clears a lower bar — and it adds real context: the read spans every frame, it operates in the caller's own Chrome tab group, and refs go stale on page change requiring a re-read. What it omits is failure behavior when no browser or tab is available.

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

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

Three sentences, front-loaded with the action and scope, then environment, then the ref-lifecycle caveat. No filler, though the middle sentence about the tab group is somewhat dense and could read more cleanly.

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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description supplies the remaining essentials an agent needs — cross-frame scope, which Chrome context it runs in, and ref staleness — for a zero-required-parameter read tool.

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

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

Schema description coverage is 100%, so tab_id, workspace_id, conversation_id and workspace_scope are all documented in the schema itself. The description adds no meaning beyond that for any parameter, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource — 'Read the text the page shows, every frame included' — and scopes it to the Well tab group. It distinguishes itself implicitly from well_browser_read_page by naming that tool only as the source of refs, though it never states the text-vs-structure contrast outright.

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 names the related tools (well_select_browser for picking the tab, well_browser_read_page and well_browser_find as ref sources) and gives a clear re-read rule when refs go stale. However, it never says when to prefer this over well_browser_read_page, which is the closest sibling and the decision an agent actually has to make.

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 destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds the execution environment (Well tab group of the caller's own Chrome, resolved via well_select_browser or the sole connection) and the staleness hazard, but never explains why the call is destructive or what state it can alter on the page.

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-loads the accepted input formats and bounds in the opening sentence, then the exclusions and environment. Slightly overpacked, and the closing remark about refs going stale does not map to any parameter on this tool, so it is marginally wasted.

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

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

An output schema exists, so return values need not be described. For a destructive browser-input tool the description covers environment, workspace scoping context, and retry semantics via the annotated idempotency_key, leaving only the nature of the destructive effect unexplained.

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

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

Schema coverage is 71% and most optional parameters carry their own descriptions, yet the key parameter 'text' has no schema description at all — the description supplies its full syntax (key name, chord, space-separated sequence) and the repeat range, which is real added meaning. The trailing sentence about refs, however, refers to a parameter this tool does not expose.

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 concrete verb and resource (press key/chord/sequence) with literal examples like "ctrl+a" and "Tab Tab", plus the repeat bound. An agent can distinguish this from well_browser_type and well_browser_left_click purely from the description.

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 names the excluded inputs (Enter, Return, Space) and routes them to the alternative action (click by ref), and states that stale refs require a fresh read before acting. That is a clear when-to-use / when-not-to-use rule set.

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 destructiveHint=true and openWorldHint=true; the description adds genuinely new behavioral facts – the domain-level refusal of pay/order/book controls, the fact that the click lands in the caller's own Chrome tab group, and that refs invalidate on page change. It does not restate annotation content, which is exactly the right division of labor.

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 correctly with the core action first, but the payment refusal is stated twice in near-identical form ('Well refuses a control that pays, orders or books' followed by 'A payment, an order or a booking never runs through the well_browser_* tools'). That duplication and the tangential tab-group sentence weaken an otherwise tight definition.

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

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

For a mutating browser action with an output schema and rich annotations, the description covers the risky edge cases an agent would otherwise get wrong: payment refusal routing, ref lifecycle, and which browser/tab group is targeted. What remains unexplained is safely delegated to annotations and schema.

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

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

Schema description coverage is 86%, so the structured fields already carry most parameter meaning; the baseline is 3. The description does add one real semantic not in the schema – that refs go stale when the page changes and must be re-read – which lifts it above pure redundancy, but modifiers, workspace_scope, conversation_id and idempotency_key are left entirely to 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?

Opens with 'Click an element by ref' – a specific verb and resource that separates it from well_browser_type, well_browser_form_input and well_browser_key. It does not explicitly state which sibling to prefer for non-ref interactions, but the ref-based targeting is distinctive enough to place it.

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

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

Gives clear when-not guidance (payment/order/booking controls are refused and must go through well_create_browser_task) plus prerequisites for tab selection via well_select_browser and re-reading after stale refs. Lacks a plain positive 'use this when you need to activate a button or link' statement, so it stops short of full coverage.

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 say readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description adds real context beyond that: the action occurs in the caller's own Chrome's Well tab group, the browser must be chosen via well_select_browser, and page refs go stale after the page changes. It does not cover failure behavior or rate/timeout characteristics, keeping it short of a 5.

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

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

The first sentence is well front-loaded and dense; the second carries the environment prerequisite. The third sentence about refs is confusing in context because no ref parameter exists in the schema and its placement after the browser-selection sentence disrupts the flow.

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?

Output schema and annotations exist, so return values and safety profile need not be explained. What is missing is precisely the information an agent needs to call it correctly: how to request back/forward, and what url accepts besides an http(s) address — a real gap given url is the only required parameter.

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 83%, so the baseline is 3. The description adds that url takes an http(s) address and that back/forward are possible, but never says how back/forward is expressed (presumably a sentinel value in url) and introduces "refs" without a corresponding parameter, leaving the key parameter's accepted values ambiguous.

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 ("Open an http(s) address in a Well tab") plus the history-navigation variant, which is far more informative than the title "Open an address". It differentiates itself from well_browser_read_page and well_browser_find by naming them as ref sources rather than covering the same action, though the refs remark muddies what the tool itself accepts.

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 acts in the Well tab group of the caller's own Chrome, picked with well_select_browser (or the only one connected)" gives a useful precondition and names the sibling that selects the browser. However there is no explicit when-not guidance (e.g., use well_browser_new_tab to open a fresh tab, well_browser_left_click to follow a link) even though those siblings exist in the same group.

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 a non-read-only, open-world, non-destructive operation, so the description's added value is in saying the tab is created in the user's real Chrome and immediately becomes active, a visible side effect. The closing sentence about refs going stale does not apply to a brand-new blank page and dilutes rather than clarifies 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 first two sentences are tight and front-load the action and its context. The third sentence about refs and re-reading after page changes is boilerplate that does not belong in a tool that creates a blank tab, so not every sentence earns its place.

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

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

For a simple browser-tab tool with annotations and an output schema, the description covers the essential context: which browser, which tab group, and that the new tab becomes active. Only the stray ref-management sentence detracts from an otherwise adequately complete definition.

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

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

Schema description coverage is 100% and none of the four parameters (workspace_id, conversation_id, idempotency_key, workspace_scope) are discussed in the description, so the schema carries the full parameter burden. That makes the baseline 3 correct here, with no extra meaning contributed.

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 ('Open a new blank tab in the Well tab group and make it the active one'), which clearly separates it from well_browser_remove_tab and well_browser_tabs_context. It stops short of naming an alternative sibling outright, so it sits just under the top mark.

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 a useful prerequisite, the tab group comes from well_select_browser or the single connected browser, and specifies opening in the caller's own Chrome. It never says when to prefer this over well_browser_navigate for reaching a URL, and it does not explain when a new tab is needed versus reusing an existing one.

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 genuinely non-structured behavior: scoping to the caller's own Chrome tab group, the default 15-level depth, and the crucial warning that refs are stale after page changes and must be re-read. Return format is also spelled out. It does not describe an error mode for a stale ref, which would complete the picture.

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

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

Three dense sentences, front-loaded with the output format before the parameter notes and the environment/staleness caveats. The telegraphic style ("ref reads one element's subtree") is efficient but slightly terse, and the tab-group sentence interrupts the parameter flow.

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 browser page-reading tool with seven optional parameters and an output schema, the description supplies what the structured fields cannot: the line format, depth default, tab-group targeting, and ref lifecycle. An agent can invoke it correctly and knows to re-read after mutation.

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 57%, and the description compensates for the undocumented parameters by explaining filter, ref and depth semantics, including the default depth of 15, which the schema does not state. tab_id, workspace_id and conversation_id are covered by schema descriptions, so the meaningful gaps are closed.

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

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

The description names a specific verb and resource ('read the page') and defines exactly what the output looks like: one line per element with role, name and ref, indented by depth. It stops short of contrasting itself with well_browser_get_page_text, which is the closest sibling an agent might confuse it with, so differentiation is only partial.

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

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

It explains the practical knobs (filter=\"interactive\" for controls only, ref for a subtree, depth default 15) and states the operational prerequisite: the tool acts in the caller's own Chrome tab group picked with well_select_browser, or the only connected one. It also gives a clear re-read rule when refs go stale. No explicit when-not guidance versus get_page_text or wait.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description is consistent with a non-data-destroying mutation while adding context the annotations cannot: the operation is confined to the caller's own Chrome and to the Well tab group. The stale-ref warning is genuinely behavioral information beyond structured fields. It stops short of saying what happens if the last tab is closed or whether in-page state is lost.

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

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

Three sentences, front-loaded with the action and scope, with no filler. The middle sentence is slightly dense ("It acts in the Well tab group of the caller's own Chrome, picked with...") but every clause carries operational meaning.

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

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

For a single-required-parameter tab-close tool with an output schema and rich annotation coverage, the description supplies what the structured fields cannot: browser selection, tab-group scope, and ref staleness. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema coverage is 80%, so the baseline is 3; the description earns an extra point by giving the required tab_id an origin (read_page/find) and a lifecycle rule (goes stale when the page changes). The remaining workspace/conversation/idempotency parameters are already well documented in the schema, so no further compensation is needed.

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 ("Close one tab") and immediately scopes it to "the Well tab group," which distinguishes it from well_browser_new_tab and well_browser_tabs_context. An agent can tell what is being removed and from where 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?

Names the prerequisite selector (well_select_browser, or the single connected browser) and tells the agent where the tab reference must come from (well_browser_read_page or well_browser_find). It also gives an explicit re-read rule when a ref goes stale. It does not explicitly contrast with siblings like well_browser_tabs_context, so it falls short of a full when/when-not routing statement.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine context beyond that: it operates on the caller's own Chrome, in the Well tab group, and assumes a browser already selected. It says nothing about whether the capture waits for the page to settle or whether it is viewport or full-page, which are the behaviors an agent would actually need to know.

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 purpose is front-loaded in the first short sentence, which is good. The third sentence about refs and re-reading the page is off-topic for a screenshot call, which takes no ref, and reads as text carried over from a click/type tool; it costs space and invites confusion.

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?

An output schema exists, so return values need not be explained, and the browser-selection prerequisite is stated. What is missing is anything about capture semantics (viewport vs full page, waiting for load) and the spurious refs advice actively detracts from an otherwise adequate definition.

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

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

Schema coverage is 100%, so baseline is 3 regardless. The description only reinforces the tab/browser defaults already spelled out in the tab_id and workspace_id descriptions, and its sentence about refs going stale maps to no parameter in this schema — misleading noise rather than added 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?

"Capture what the tab shows" gives a specific verb and resource, and the second sentence scopes it to the Well tab group of the caller's own Chrome. It stops short of distinguishing this from the sibling well_get_browser_task_screenshot, so an agent must infer which screenshot tool applies to a live tab versus a browser task.

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 usefully states that the browser is chosen via well_select_browser (or the single connected one), which tells the agent what precondition to satisfy first. However, it names no when-not condition and never contrasts the screenshot with well_browser_get_page_text (text) or well_browser_read_page, so the choice between capture and read is implied at best.

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 destructiveHint=false and openWorldHint=true, and the description adds context beyond them: the operation targets the caller's own Chrome tab group, requires a prior browser selection, and that refs invalidate on page change (a real failure mode with a prescribed remedy). It does not say what happens when the ref is no longer present or whether it retries/waits, which keeps it at 4. Nothing contradicts the readOnlyHint=false annotation, since scrolling does mutate page state.

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

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

Three short sentences, front-loaded with the action, then environment scoping, then the ref lifecycle hazard. Every sentence carries distinct information an agent needs before calling; nothing is redundant with the title or annotations.

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?

An output schema exists, so return values need not be explained, and the rich schema covers the workspace/conversation plumbing. What remains is behavioural: element-not-found handling, whether the scroll waits for loading content, and how it relates to well_browser_wait — minor gaps for a six-parameter tool whose remaining surface is well documented.

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

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

Schema description coverage is 100%, so all six parameters (tab_id, target, workspace_id, conversation_id, idempotency_key, workspace_scope) are already documented in the schema, and the baseline is 3. The description adds one piece of genuine meaning beyond the schema — that refs go stale on page change and must be re-read — but says nothing additional about tab selection defaults or workspace scoping.

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 precise mechanism: 'Scroll the page until the element of the ref is in view.' The target is unambiguous (a ref-based element), and it names the tools that produce refs (well_browser_read_page, well_browser_find), which implicitly separates it from the clicking/typing siblings. It stops short of explicitly contrasting itself with siblings like well_browser_wait, which is why it isn't a 5.

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 the prerequisite chain clearly: the action occurs in the Well tab group chosen via well_select_browser (or the only connected one), and refs must originate from well_browser_read_page or well_browser_find. It adds a concrete recovery rule — 'read again then' when refs go stale. No explicit when-not-to-use or comparison to well_browser_wait, so not a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true. The description adds genuinely useful behavior beyond them: which Chrome instance is targeted and how that target is selected via well_select_browser, plus the volatile nature of page references.

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

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

The first two sentences are efficient and front-loaded with scope and target selection. The final sentence about refs coming from well_browser_read_page/well_browser_find and going stale is tangential on a tool that returns no refs and takes no ref parameter, so it costs space without earning 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?

Rich annotations and an output schema mean the description need not explain return values or safety. It covers the one non-obvious thing — which browser and tab group it reads — but leaves the workspace_scope parameter's effect (family merging vs. per-workspace figures) unaddressed.

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 workspace_id, conversation_id and workspace_scope are already documented in detail. The description adds nothing about them — notably it does not mention the workspace_scope=family behavior — so the baseline 3 applies.

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

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

States a specific verb and resource ('List the tabs of the Well tab group') and enumerates exactly what comes back: tab_id, title, URL, and the active one. That is enough to distinguish it from well_list_browsers and the other well_browser_* action tools without opening any schema.

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

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

Explains the context of use — it operates on the caller's own Chrome, in the tab group chosen through well_select_browser, or the single connected one. It does not explicitly contrast with well_list_browsers, so the when-to-prefer-this-tool decision is only partially spelled out.

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 give the generic write/destructive/open-world profile; the description adds genuinely non-obvious behavior: it refuses to type into password, card or code fields, and it operates only in the caller's own Chrome tab group rather than a remote browser. It does not say whether existing field content is replaced or appended, which matters for a destructiveHint=true 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 opening sentences are tight and front-loaded with the action and the click-first precondition. However the closing sentence about refs going stale is a dangling, misleading paragraph for a tool whose schema has no ref field, so it costs space without earning 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?

An output schema exists, so return values need no explanation, and the safety constraints are covered. But for a write tool with six parameters the description leaves open how the target element is chosen (no ref parameter exists) and whether typing commits the form or replaces existing text.

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 83%, so the baseline is 3 and the description adds nothing about text, tab_id, workspace_id, conversation_id, idempotency_key or workspace_scope. Worse, it discusses refs coming from well_browser_read_page/well_browser_find, but no ref parameter exists in the schema — the guidance points at targeting mechanics this tool does not accept.

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 ("Type text where the focus is") plus scope (the Well tab group of the caller's own Chrome). It does not distinguish itself from the close sibling well_browser_form_input or well_browser_key, so an agent choosing between text entry tools still has to guess.

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 concrete preconditions ("Click the field first") and names the routing tool well_select_browser and the read tools that supply targets. It stops short of naming exclusions among siblings — notably when to prefer well_browser_form_input over ad-hoc typing.

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?

Adds real context beyond the annotations: the tool operates in the Well tab group of the caller's own Chrome, defaulting to the active tab. However, the key behavioral question for a wait tool – whether it returns early when the page changes or always blocks for the full duration – is left unanswered, and the refs-staleness note describes neighboring tools more than this one.

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 with the core action and duration bound, then context, then the caveat. The final sentence about refs going stale is useful workflow guidance but slightly tangential to the wait itself; nothing is redundant.

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

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

An output schema exists, so return-shape explanation is not required. The description covers scope, tab targeting, and the re-read workflow, which is nearly enough for a low-complexity tool; only the early-return/blocking semantics remain a gap.

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

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

Schema coverage is 80%, so the baseline applies. The description restates the duration range already in the schema and does not explain tab_id, conversation_id, workspace_id, or workspace_scope semantics; the well_select_browser mention relates to browser selection rather than any parameter.

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 (wait) with a bounded range (0-30 seconds) and a target (the page changing), and names the tab group and selector sibling well_select_browser. It is clearly distinguishable from the other browser siblings, though the phrase 'for the page to change' leaves open whether the wait ends early on change.

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

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

Implies the wait is used between a page-changing action and a re-read, and points at well_browser_read_page / well_browser_find as the source of refs. It never states explicitly when to prefer this over re-reading directly or over well_wait_for_selection, so the agent must infer the trigger condition.

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

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

Goes well beyond the destructiveHint/idempotentHint annotations: cancellation is permanent and non-resumable, an in-progress run is not stopped, the morning brief is disabled-but-preserved and re-enableable, and no confirmation card is drawn so the agent must confirm verbally. That is precisely the destructive-behaviour context an agent needs.

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

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

Front-loads the irreversible nature and the morning-brief exception, which is the right ordering. However, the brief-disabling behaviour is stated twice (once early, once in the usage-guidelines paragraph), and the multi-workspace guidance is padded with a wordy 'this read will not guess' sentence, so a trim would help.

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 needn't explain return values, and it still tells the agent to quote the returned status. For a destructive single-target write with five params, every decision the agent must make is covered: which tool, how to confirm, and which workspace to target.

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 real value by giving schedule_id provenance (well_list_schedules or the create result) and by telling the agent to pass workspace_id only when the token authorizes several workspaces. It does not explain idempotency_key behaviour beyond what the schema already says.

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 ('Cancel one workspace schedule for good') and immediately scopes the special case (morning brief). It distinguishes itself from siblings like well_snooze_schedule and well_update_schedule by name, so an agent can select it without opening any schema.

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

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

Gives explicit when-to-use examples ('turn off my brief', 'disable my morning brief') and explicit when-not-to-use with the exact alternative for each case (snooze for a few days, update_schedule with status 'paused' for a reversible pause, update_schedule to change). Nothing is left to inference.

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

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

Annotations already mark this as read-only/non-destructive, and the description adds real behavioral context beyond that: exact IBAN comparison across every currency pocket, the six possible status outcomes, truncation behavior and its guarantee that the checked IBAN is always read, and the thin-history caveat on known_payment_count.

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 with the core action and trigger, then organized into discrete status/return blocks. It is long, but nearly every sentence (status definitions, truncation caveat, workspace rule) carries information an agent needs to interpret the result; a little tightening would earn a 5.

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

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

Given five parameters, rich annotations, and an output schema, the description covers everything an agent needs: when to call, how to pass IBAN/workspace_id, all status meanings, the truncated/never_seen interaction, and the safety caveat against over-trusting the answer.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds meaning on top: 'pass the IBAN as given; spaces and lower case are fine', exact-match comparison semantics, and an explicit rule for when workspace_id must be supplied. It does not explain conversation_id or workspace_scope, which the schema alone carries.

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 (check one IBAN against what Well knows of one supplier) plus scope ('one supplier', 'one bank account'). It is clearly distinguishable from siblings like well_update_supplier_bank_account (mutates) or well_search_company_registry (looks up companies), and the 'draws no card' note contrasts it with payment 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?

Explicit trigger: 'Use it when a person forwards new or changed bank details for a supplier ... before they pay', including the mail/invoice/typed-message contexts. It also names the boundary ('never blocks a payment', 'never call new bank details safe from this answer alone') and the workspace_id selection rule.

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 cover readOnly/destructive/openWorld; the description adds the high-value operational facts an agent cannot infer: single-use token, one-hour expiry from the drop, refusal states are terminal (expired/already claimed/unknown), and that 'failed' files were claimed but did not ingest. This directly shapes recovery 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?

Front-loads the core action and the too-many-calls-per-file warning immediately, then sequences follow-up, expiry, and failure handling. Dense with actionable content, though the multi-paragraph form is longer than strictly necessary for a single-claim tool.

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

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

With an output schema present and five parameters, the description still covers the return contract (one document_id per file, poll each), the token lifetime, and terminal-failure handling. Nothing needed to invoke or recover correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema: it tells the agent the link can be passed verbatim because the tool extracts the token, and it explains the omit-vs-require logic for workspace_id when the token authorizes multiple workspaces.

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

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

States a specific verb+resource+scope: claiming every bank statement the user dropped on Well's website via one claim token. It also implicitly distinguishes itself from well_get_statement_import_result, which it names as the follow-up poll target, and from the upload tools by requiring a token rather than file bytes.

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?

Explicit about when to call (once per token, never per file), what to pass (the token or link 'exactly as given'), what to do after (poll well_get_statement_import_result per document_id), and what never to do (never retry a refused token; ask for failed files by hand). This is a full call protocol, not just a context hint.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial context: ranking rules, exclusion reasons (expired, unreadable validity, mismatches), mixed-currency handling, refusal reasons, and the non-snapshot, member-only nature of the share url. It does not contradict 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 and structured, with purpose and usage before detailed ranking and exclusion rules. However, it is long and includes an enumeration of output fields that the output schema already defines, which reduces conciseness.

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

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

Given the complex ranking and exclusion logic, the description covers purpose, usage, behavioral rules, refusal reasons, and workspace selection. With an output schema and rich annotations already present, nothing material is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for quote_request_id (omit to list groups) and workspace_id (required only when multiple workspaces are authorized), though it does not explain conversation_id or workspace_scope beyond what the schema already provides.

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

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

The opening sentence states a specific verb and resource: compare supplier quotes of one comparison group, read from quote documents, and explicitly says it writes nothing. It also distinguishes the read from well_group_quotes, which creates groups, so an agent can identify the tool without opening the schema.

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

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

The description explicitly instructs to call with quote_request_id to compare a group or with no argument to list groups and ungrouped quotes, and names well_group_quotes as the tool that sets groups. It also covers workspace_id usage (direct when one workspace, pass workspace_id when several) and warns never to call the share url public.

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

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

Annotations only say readOnly and closed-world; the description goes much further by disclosing DST gap/overlap behavior (shifted_forward, earlier_of_two), the accompanying adjustment and note fields, the full error_reason taxonomy, and the rule to never guess a zone or fall back to UTC. That is exactly the behavior an agent could 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?

It is long, but front-loads the when-to-call rule and then layers format, returns, DST edge cases, errors, and workspace behavior in a sensible order. Almost every sentence carries decision-relevant information; the section on conversation_id/workspace_scope is left to the schema, which keeps the prose from bloating further.

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 an output schema, six parameters, and nontrivial time-zone edge cases, the description covers the call conditions, the input format, the return shape, DST ambiguity, and every error path. An agent could invoke and recover from this tool without consulting anything else.

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 parameter descriptions already do the baseline work. The description still adds meaning beyond it: the no-offset/no-Z format requirement for local_time, the 'leave to_timezone out means the user's own zone' default, and the token-conditional workspace_id rule. The added value is real but partly restates the schema 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 description names a precise verb and resource (convert a wall-clock time from one IANA zone to another) and pins down the exact output fields (instant_utc, from, to). It also makes itself the mandatory route for any offset arithmetic ('never work out an offset or a daylight-saving change yourself'), which separates it from doing the math manually and from calendar-event tools it feeds.

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

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

It states the triggering condition with concrete user phrasings ('3pm New York time', 'what time is that for me?'), explains when to omit to_timezone versus pass it, and says when workspace_id is needed. The error branch for 'user_timezone_unknown' explicitly tells the agent to ask the user and what to do in a scheduled run where no one can answer.

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 this is a non-destructive write; the description adds the real behavior: exact-name matching with normalization, numbered-choice fallback instead of fuzzy guessing, time-zone-derived day default, and a two-step save where the Harvest entry is sent only after the person approves its card. These are material behaviors an agent could not infer from 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?

Purpose and the project/day rules are front-loaded, which is good, but the final paragraph details receipt fields (activity.week.total_hours, source_ids) even though an output schema exists, and lines like 'the sender is the person whose hours are logged' are filler. The density is justified by tool complexity, but some of the length is not.

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 10-parameter write tool with Harvest bridging and ambiguity handling, the description covers selection, defaults, failure paths, and the approval gate. With annotations and an output schema both present, nothing an agent needs in order to invoke it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds precedence and constraint meaning the schema does not: project_id is the path for MCP calls, day must never be computed by the agent, duration_seconds must be a positive whole number, and the Harvest connector id comes from a live row in well_list_connectors. This meaningfully exceeds the schema 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 gives a specific verb and resource: logging the sender's time against a live project in the workspace, which separates it from well_list_activities and well_update_activity. It does not name a sibling explicitly, so differentiation is implied rather than stated.

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?

Explicit conditions throughout: pass project_id from well_list_projects when known, project_name only when it normalizes to exactly one live project, omit day for today unless Harvest, and set also_in_harvest only on an explicit request. Alternatives and failure paths (number of matches, ambiguous Harvest tasks) are spelled out, 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?

Beyond the annotations it discloses substantive behavior: the create is immediate ('the agent is saved at once'), the resulting seat is a member-role-only identity that never holds invoice rights, never signs in, and can never be owner/admin/person. It also surfaces a uniqueness constraint ('two agents of one workspace never share a name') and the exact success/error return shape, which is exactly the kind of side-effect detail an agent needs before writing.

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

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

Well front-loaded: purpose first, then the trigger condition, then parameter summary, then constraints, then return shape. A few sentences are ornamental ('the complete order is the yes', 'the line that says what it handles') and could be trimmed, but the information density is high and the ordering matches how an agent reads a definition.

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?

An output schema exists and the description still summarizes the return contract compactly, and it covers the permission requirement, the name-uniqueness rule, identity constraints, and defaulting behavior for the sponsor. Combined with 100% schema coverage on the remaining operational parameters, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so all seven parameters — including workspace_id, conversation_id, idempotency_key and workspace_scope — are already documented in the schema. The description's 'REQUIRED: name / OPTIONAL: duty, sponsor_membership_id' block mostly restates that, though it usefully reiterates that sponsor defaults to the requesting person. Baseline 3 applies since the schema carries the 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?

States a specific verb and resource — 'Add an agent to the current workspace' — and then defines the seat object concretely (name, duty, sponsor). An agent can distinguish this from well_update_agent_seat or well_delete_agent_seat by the 'Add'/'saved at once' framing, but the description never names those siblings explicitly, leaving that inference to the verb alone.

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 a clear trigger ('Use this tool when an owner or an admin asks to add an agent') with a realistic example utterance, plus the permission gate ('Only an owner or an admin adds one'). It does not state when to prefer an alternative tool (e.g., update vs. create, or hand-off to well_list_agent_seats to check name collisions), so it falls short of full routing 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?

Goes well beyond annotations: names the failure modes ('a tile that takes no comment, a part the board does not show, or a reply to a comment that holds no question fails, and nothing is written'), the return shape, and an explicit prompt-injection warning about untrusted-content markers. This is consistent with readOnlyHint=false/destructiveHint=false while clarifying that the write is append-only.

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 with purpose and side-effect scope, then usage, then requirements, then return/failure, then a safety note. Each section earns its place; the required-parameter restatement is the only mild redundancy and it is compact.

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 9-parameter write tool with an output schema, the description still covers failures, return shape, and untrusted-content handling. Nothing an agent needs to invoke it correctly — target semantics, null cases, reply case, error behavior — 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 baseline is 3; the description adds value by explaining the null semantics in prose ('null for the whole tile', 'null for a new comment') and pointing at well_list_board_comments as the source for parent_comment_id. It repeats the required list rather than adding new constraints, keeping it below 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?

States a specific verb+resource ('Add a comment to a part of a board') and pins down the semantic ('a comment asks for a change of that part') plus the side-effect scope ('nothing on the board changes'), which separates it from the update/delete/send comment siblings. An agent can identify what this 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?

Gives explicit trigger conditions ('when the person asks to note a change on a board for later, or to reply to a question that the agent asked on a comment'), which is clear positive guidance. It does not name the alternatives (well_update_board_comment, well_send_board_comments) or state when not to use it, so it stops short of a 5.

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

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

Annotations declare a non-destructive, non-idempotent write; the description adds context annotations cannot express, such as the mandatory draft-first workflow, the default values applied when the user is silent (18:00 end, dark theme, month calendar view), and that a succeeded create never mutates an existing page. It stops short of stating collision/error behavior for a duplicate slug, which would matter for a create with a user-chosen address.

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 with purpose then immediately the routing rule, and nearly every sentence carries decision-relevant information. It is a dense single block of roughly 250 words, though, with the weekly_hours explanation mid-stream; the calendar/theme defaults could be tightened and sub-structure would aid scanning for a 14-parameter tool.

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 14-parameter create with high-stakes workflow dependencies, this covers the required workflow ordering, all format conventions an agent would otherwise get wrong, and the mutate-vs-create boundary. Return values are covered by the existing output schema, and workspace_id/conversation_id/idempotency_key conventions are covered by schema descriptions, so no critical gap remains.

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 only 29%, so the description must carry the load and largely does: it explains slug via the /c/<workspace>/<slug> link form with a worked example ('gods' from /c/zachary/gods), member_slug's scope restriction ('pass it only when the user asks to choose that, on their first page'), primary_color's hex requirement and name-to-hex conversion, weekly_hours' day-numbering, HH:MM format, entry-merging rule and break-splitting rule, plus theme and calendar_view defaults. title, location, description and duration_minutes get no explicit treatment, leaving a minor gap against a 14-parameter 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?

Opens with a specific verb+resource ('Create a booking page') and immediately glosses it as 'the public link where people book a meeting with the user', which disambiguates it from siblings like well_create_schedule, well_create_calendar_event and well_update_booking_page. An agent can identify the target artifact without opening any schema.

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

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

Explicit routing rules: call well_get_booking_page_draft first when the host can draw cards, call this tool 'only when that result says card_drawn is false or when the user asks in chat to create it now', and an explicit negative rule that an existing page is changed via the draft tool and booking_page_id, 'never by a new create'. This is model when-to-use guidance including alternatives and exclusions.

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

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

Annotations only cover the safety trio (readOnly false, destructive false, openWorld false); the description adds substantial context beyond them, including confirm cards, the WhatsApp confirmation escape hatch, the browser_task_confirmation_on_whatsapp and browser_task_start_host_unknown codes, and what happens to payment (stops at the payment page). However, openWorldHint=false sits awkwardly against prose that has the tool dispatching runs to live external websites and cloud browsers, and the description does not resolve that tension, so it is not fully consistent with the structured metadata.

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

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

The text runs roughly 1,500 words of dense prose with heavy repetition — the instruction never to ask the yes yourself appears four times in different sections, and the errand-site fallback rules are restated under both the plan and goal_kind sections. It is front-loaded with the required fields, but an agent must read the whole block to find which paragraph governs its case.

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

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

For a tool this complex the description covers the main flows (single run, errand plan, saved-task rerun, portal and invoice fetches) and even restates return fields despite an output schema existing. But it omits or barely touches several schema parameters that affect behavior, and the return-value prose duplicates the output schema rather than using that space to close the remaining parameter gaps.

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

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

With 30 parameters and 67% schema description coverage, the schema already carries most field meanings, including the deeply nested browser object. The description adds genuine combination rules (leave out dedup_key, chase_invoice_id and parent_task_id with browser or errand_steps; request_terms required for a purchase; task_kind required with run_in_background), but it never explains several top-level parameters (steps vs errand_steps, priority, references, brief_point, hand_to_well, source, status, workspace_scope), so coverage remains uneven.

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 names three distinct capabilities with specific verbs and resources: start a browser task on a website, rerun a saved browser task, and create an errand plan of several website steps. It then defines the resource itself ("A BROWSER TASK is a task Well does on a website for the person who asks"), which separates it from an ordinary task-creation call and from the browsing primitives 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?

Usage is exhaustively gated: only the person's own message in this turn, first call of the turn, never from a forwarded message, mail or page, and specific routing to siblings (well_list_missing_invoices for counterparties, well_preview_browser_skill for saved-task ids, well_list_browser_task_states for follow-up). It also states when a rerun needs no task read and when a repeated ask returns browser_task_already_open instead of creating anything.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), it discloses the ten-minute idempotency-replay behavior and how to bypass it, the calendar_scope_not_granted failure with a link the agent must surface verbatim, the side effect of task_id linking an event to a job slot, and an explicit rule not to write the time into both the task and the event.

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?

Purpose and usage routing are front-loaded well in the first three paragraphs, but the tail drifts: the closing block mixes conversion guidance, and the sentence 'On an update, never look an event up only to read its zone' belongs to the update tool rather than this one. The person_order paragraph documents a parameter that does not appear in the input schema at all.

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 17-parameter write tool this is largely complete: idempotency, auth failure, time-zone handling, task linkage, and attendee notification are all addressed, and the output schema means returns need not be restated (though they are). The unexplained person_order reference and undocumented visibility/workspace behavior leave minor holes.

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

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

Schema description coverage is only 29%, and the prose compensates heavily: exact timestamp format with offset, the all-day convention where end_at is the day after, 'send timezone on every create', recurrence as RRULE lines, attendees as email addresses, and a default-plus-exception rule for notify_attendees. Gaps remain for visibility and the workspace/conversation parameters, which are only documented in the schema.

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

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

The opening sentence names a specific verb and resource with scope: 'Create an event on one of the user's own Google calendars.' It is immediately distinguishable from well_update_calendar_event and well_delete_calendar_event, and the ownership constraint ('own calendars') frames the domain.

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 enumerates the triggering phrasings ('schedule, book, add or set up a meeting or an event') and gives explicit routing rules: default to calendar_id 'primary' without a lookup, call well_list_calendars only when a non-primary calendar is named, and call well_list_calendar_events when the event may already exist. Alternatives and preconditions are both covered.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the agent knows this is a safe-but-mutating create. The description earns credit for the security constraint (full PANs rejected), but says nothing about permissions, duplicate handling, or what a created card affects downstream.

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

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

Two short sentences, front-loaded with the action and then the one constraint that prevents a failed call. Nothing extraneous.

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?

An output schema and rich workspace_id/conversation_id/idempotency_key descriptions in the schema cover much of the surrounding complexity, and the description covers the core create action. Still missing is context on how a card record relates to accounts or transactions, which would help an agent decide to create one at all.

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

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

Schema description coverage is only 36% across 11 parameters, so the description is expected to compensate — but it only addresses last_four_digits and waves at "optional card details." Fields like type, brand, issue_date, start_date, expiration_date and cardholder_name remain undocumented in both places.

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?

"Add a workspace card record" states a specific verb and resource, and the second sentence narrows the payload to last-four-digits only. It is clearly a creation tool, distinguishable from well_update_card and well_delete_card by the verb alone, though neither sibling is named.

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 instruction to supply only the final four digits is a real usage constraint, but there is no explicit when-to-use/when-not guidance relative to well_update_card or well_delete_card, and no mention of what prerequisites a card record needs before creation.

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