hedwigai

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

Adds behavior well beyond the annotations: lifetime ('stays attached for every later run until removed'), same-name replacement, a 32 MB size cap, and the crucial side-effect note that 'nothing runs and nothing is billed.' The replacement rule is consistent with idempotentHint=true rather than contradicting it.

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

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

Four short sentences, zero filler, ordered by importance: what it does, lifetime, constraint, next step. The most decision-relevant facts (persistence, no run triggered) come early.

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?

No output schema exists, yet the description covers what an agent needs: the attachment's lifetime, replacement semantics, size limit, billing/run side effects, and the sibling call that actually consumes the attachment. Nothing material is left unspecified.

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 are documented in the schema itself. The description adds only the global 32 MB constraint, which is not tied to a specific parameter, 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 ('Attaches one file to a workbook') and immediately gives scope ('one file', attached for runs to read and cite). An agent can distinguish it from list_attachments and remove_attachment without opening 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 clear context (files exist so runs can read and cite them) and explicitly routes the agent to the follow-up step: 'start a run with update_workbook to use it.' It does not state any exclusion or when an alternative attachment mechanism is preferable, so it stops short of full when/when-not 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 declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false; the description adds real value beyond these by disclosing that 'yes' starts a run billed to the account and that any answer is persisted so the question is not asked again. These are meaningful side effects (billing, run creation, state change) that the annotations alone do not convey.

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

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

The content is informative and each sentence carries some payload, but it reads as a conceptual narrative rather than a front-loaded definition, and the core 'this tool records a workbook's answer' statement arrives only after the framing about what a workbook 'is asking.' It is reasonably sized but not tightly structured.

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

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

There is no output schema, so the description must carry behavioral weight, and it does explain the yes/no outcomes, persistence, and billing side effect. It stops short of describing the run that 'yes' starts or any permission requirements, but for a two-decision tool with 100% schema coverage and clear annotations this is largely complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantive meaning to the enum by spelling out what 'yes' and 'no' each cause (record decision + start billed run vs. record that the document was judged still good). The 'context' and 'llm_model' parameters are already fully documented in the schema, so nothing is missing.

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 establishes a specific verb+resource: recording an answer to a question a workbook is 'asking,' with the concrete current case (sources moved under the current version). An agent can distinguish this from recheck_sources or save_sources, though it never names those siblings explicitly. The action itself is described narratively rather than front-loaded, which slightly blunts clarity.

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 trigger is implied ('shown as asking when it is read'), and the yes/no branches are explained, giving usable context for when a call is warranted. However, there is no explicit when-not guidance and no named alternatives (e.g. recheck_sources, save_sources) to route between. Usage is therefore inferable but not directive.

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 establish read-only/open-world/non-idempotent, and the description adds substantial context on top: the exact answer vocabulary including 'unsure' and 'invalid_premise', the refusal-to-guess policy, that amounts are compared in code against a program's returned figure, and that any programs run are billed to the account. This is rich behavioral disclosure well beyond the annotations.

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

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

The core purpose is front-loaded before the mechanics, and most sentences carry real information (answer values, sources, billing). It is a dense single paragraph with some heavy nesting, costing a point on readability, but little is wasted.

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

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

With no output schema, the description carries the return-value burden and does so: it names `answer`, `claims`, `sources`, and `probabilities`. Combined with the mode and billing notes, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including the context character limit and the options/answer relationship. The description reinforces the context-vs-options interplay but adds little syntax or format beyond what the schema provides, 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 (answers a short word/value question) with concrete examples and a clear source scope (this account's workbooks and programs, no run started). The behavior is easy to grasp. It does not, however, explicitly differentiate itself from the sibling 'answer_question', which by name sounds overlapping, so it falls short of 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?

It clearly frames the operating modes: default lookup from workbooks/programs, or 'give context to have it answer from your own text instead, among options if you pass them.' That route selection is useful. It stops short of telling the agent when to prefer this tool over siblings like answer_question or search_workbooks, so no explicit alternatives/exclusions are given.

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 openWorld/idempotent/readOnly/destructive hints; the description adds substantial extra behavior: writes are confined to /tmp, redirects elsewhere are refused, one persistent shell per session sharing cwd and /tmp across calls, and metered programs spending prepaid credits. This is exactly the kind of operational context an agent needs to call it safely.

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 behavior and persistence/billing rules, but the two long program catalogues are dense and could be trimmed since `help` and `programs list` are described as the discovery path. Overall the sentences earn their place and structure is clear.

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 no-output-schema tool that executes arbitrary commands, the description covers the environment, persistence semantics, write restrictions, billing model, and its handoff to the workbook tools. Nothing critical to correct invocation appears missing.

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

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

Schema coverage is 100% so the parameter contracts are already documented, but the description meaningfully enriches the `command` parameter by cataloguing the available programs and the enable/billing mechanics that shape what a valid command looks like. It does not, however, add formatting or syntax guidance beyond the schema's 'pipelines, globs and control flow' note.

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 ('Runs a bash command in this account's jailed, read-only shell') and immediately characterizes the environment and the data programs reachable from it. An agent can distinguish this from the workbook-manipulation siblings 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 clear operating context (what's available, how to discover it via `help`, `programs list`, `programs enable`, `<program> --help`) and an explicit routing rule tying it to a sibling flow: check a workbook out, edit it here via bash, then commit_workbook. It stops short of stating when-not-to-use bash in favor of a dedicated sibling tool.

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

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

Despite readOnly/idempotent annotations, the description adds substantial behavioral context: session scoping (a checkout in one shell is invisible to another), the exact return contents, that derived tab markdown is non-authoritative (editing changes nothing), that current.xlsx is the file to EDIT, and that README.txt documents the xlsx commands. None of this is captured by 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 is front-loaded in the first sentence, and the remaining sentences carry real information (session scoping, return shape, commit follow-up, README pointer). It is dense and slightly long across three paragraphs, but few sentences are wasted.

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

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

With no output schema, the description compensates by describing exactly what is returned (the directory, the file to edit, per-tab files) and the read-README workflow. Combined with the session scoping and commit follow-up, an agent has everything needed to call and use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds meaning: it clarifies that `session` names another shell whose id is what `session id` prints, and that omitting it targets THIS connection's shell. It does not expand on the workbook id or analytics-only params.

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

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

The description states a specific verb and resource (check out a workbook into the shell's /tmp) and explains the mechanism that makes it necessary (tabs live in the object store, which the shell does not mount). It is clearly distinguishable from siblings like read_workbook, pull_workbook, and commit_workbook.

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

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

It gives clear context: use this to open a workbook for bash work, then call commit_workbook with the same session. It also states the linked Drive/Dropbox checkout semantics. It stops short of explicitly contrasting with sibling alternatives such as read_workbook or pull_workbook, which would be needed for a 5.

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

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

Annotations only declare readOnly=false, destructive=false, non-idempotent, closed-world. The description adds substantial behavior beyond that: the spreadsheet vs markdown commit mechanics, what survives ('formulas, formats and charts'), deletion semantics, and that the prior version is retained either way. This materially shapes invocation expectations.

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

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

Three tight paragraphs, front-loaded with the core action, then format-specific mechanics, then refusal conditions. Every sentence carries weight, though the format-specific detail is lengthy for an agent that may only need the core contract.

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

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

For a mutation tool with no output schema, the description covers the essential contract: required inputs, cross-tool parameter sourcing, format-dependent behavior, failure modes, and version-retention outcome. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds semantics the schema does not: `base_version` must be the version the checkout reported and `session` must match the checkout's shell. That cross-tool parameter linkage is genuine 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?

States a specific verb and resource ('Reads back the checkout ... and writes it as a new version') and implicitly pairs with the checkout sibling by referencing 'the checkout in your shell session'. An agent can distinguish this from checkout_workbook and restore_version without opening schemas.

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

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

Gives clear operational conditions: pass the `version` the checkout reported as `base_version` and the same `session`. Explicit refusal conditions (workbook moved past base_version, a run writing it, nothing changed) tell the agent when the call will fail. It stops short of naming an alternative tool to use instead in those cases.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: partial-patch semantics, that edits take effect only from the next run, and that `graphroom` mode runs refuse until a procedure is drawn.

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

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

The core instruction (partial update, read-only when empty, next-run effect) is front-loaded, but the mode enumeration is a long nested run-on that duplicates the schema's own mode description, diluting the structural clarity of an otherwise well-organized entry.

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

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

For a 12-parameter mutation tool with no output schema, the description covers when it writes, when it reads, when changes apply, and mode-specific preconditions. It gestures at the return value via "one of the `nodes` this answers with" but never states what a read call returns or what permissions are required.

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% across all 12 parameters, so the schema already carries the semantics and the baseline is 3. The prose mostly restates the mode enum and the model/time fields that the schema already documents in comparable depth, adding little 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 pair and resource: reading and changing a workbook's settings, with an enumerated list of what is configurable. However, it never distinguishes itself from the sibling `update_workbook`, leaving the agent to infer which settings tool applies.

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 operational context: "Send only what should change — the rest stays. With nothing to change it only reads. Changes apply from the next run," which resolves the read-vs-write ambiguity inherent to a get/set tool. No exclusions or sibling alternatives are named, 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 only declare the generic profile (not read-only, not destructive, open-world). The description adds genuinely useful behavior: the run is billed to this account, takes minutes, self-written content costs nothing and runs nothing, attachments persist for every later run, and mode/model must be set before the first run. It stops short of explaining failure/refusal behavior beyond the graphroom note.

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

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

The core decision is front-loaded in the first sentence, with consequences stated immediately. The sentence is dense and long but every clause earns its place by distinguishing modes; no filler or tautology.

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

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

For an 11-parameter creation tool with no output schema and 100% schema coverage, the description covers the decisive semantics (mode selection, billing/timing, non-destructiveness) well enough to invoke correctly. The secondary params (name, folder, model, analytics fields) are left to the schema, which is reasonable.

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

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

Schema coverage is 100%, so the schema already documents all 11 parameters, establishing the baseline of 3. The description reinforces the important semantic constraints (exactly one of the three, one call can both create and start the run), but adds little syntax or format detail beyond the schema itself.

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 ("Makes a new workbook") and immediately clarifies the three mutually exclusive creation paths with their distinct outcomes. It scopes the tool to creation via "Nothing that already exists is changed," which implicitly separates it from update_workbook/write_workbook, but no sibling is named explicitly, keeping it short of 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 explicit when-to-use guidance for the three creation modes: `instruction` for a billed, multi-minute research run, `document`/`sheets` for content you author that lands instantly and free. It does not, however, name which sibling to prefer for adjacent operations (e.g., update_workbook for editing an existing one), so it stops at clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is partly covered. The description adds genuinely non-redundant behavior: credits are prepaid and consumed per call, there are no seats or subscriptions, and the returned link must be opened by the user, not the agent — the latter being a critical operating constraint.

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 paragraphs, front-loaded with what the tool returns before the when-to-use clause. The standalone 'do not open it yourself' instruction earns its place as the sentence most likely to prevent agent misuse.

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 no output schema, the description carries the return-value burden and does so: balance in USD plus a checkout link. It also explains the billing model. It does not describe behavior when the balance is zero or the link is unavailable, which is a minor remaining gap for a zero-required-param tool.

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

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

Schema coverage is 100% with all three parameters fully documented in the schema, so the baseline is 3. The description reinforces that the link is denominated in US dollars and is used to 'add more', but adds no syntax, range, or unit detail beyond what the schema already states.

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 — shows the account's prepaid credit balance and returns a checkout link — plus the currency (US dollars). No sibling tool touches credits, and the billing model sentence (prepaid, per call, no seats) makes the tool's scope unambiguous.

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

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

Gives two concrete triggers: before a large job, or when a call is refused for credit. That is clear when-to-use guidance. It stops short of naming an alternative or stating when not to call it, but there is no plausible competing sibling for balance checking.

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 openWorldHint=true, idempotentHint=false and destructiveHint=false, but the description adds high-value context the annotations cannot: the send is irreversible ("Mail cannot be taken back") and it uses the last saved state rather than pending edits. It still doesn't describe failure modes (which addresses are silently skipped is only in the schema).

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 tight sentences with the recipient scope front-loaded, then the irreversible-action warning, then the preview escape hatch. Every clause carries 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 an irreversible outbound send with no output schema, the description covers destinations, source state, irreversibility and the dry-run path. It leaves the return value and post-send confirmation behavior unstated, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters are already documented, which sets the baseline at 3. The description reinforces the relationship between `send_to`, `members` and `preview`, but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (sends/emails) and resource (the workbook, as last saved) and names the recipient set precisely, deferring to configure_workbook's `members` and the `send_to` override. An agent can tell this apart from share_workbook or link_workbook without opening 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 a clear operating instruction — confirm recipients with the user first because mail is irreversible — and points to `preview` for a dry run. It does not explicitly contrast with the sibling share_workbook, so it stops short of naming alternatives.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real value by disclosing that 'none of these' is always an option, that null is a valid result, and by sketching the return shape. No output schema exists, so this return disclosure is genuinely load-bearing.

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 core concept and the null outcome, then scoping, then return shape. Slightly ornate phrasing ('jev's choice among the account's folders') but no filler sentences.

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 no output schema, the description correctly spends its budget explaining the return value ('found' with id/name/folder, or null). Combined with annotations covering safety and a fully-described schema, an agent has enough to call it correctly; only explicit sibling routing 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. The description's `parent` explanation mirrors the schema text ('omit for anywhere, / for the top level, or a folder path') without adding syntax or format detail, and says nothing about the `context`/`llm_model` analytics params. Adequate but not additive.

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 (find the one folder) and a distinctive mechanism — semantic choice among the account's folders, not an exhaustive listing. An agent can separate it from list_folders by the singular 'the one folder' framing, though no sibling is named explicitly.

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 use case (natural-language folder lookup when you don't know the exact path) and documents the `parent` scoping options, but never names alternatives like list_folders or find_workbook or states when not to use it. Usage is inferable rather than stated.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds real behavioral value: 'nothing is made up', the always-present 'none of these' fallback, and the exact return shape `found` ({id, name, folder}) or null. That 'no fabrication / may return nothing' trait is not derivable 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?

Front-loaded with the core behavior (one-or-none, fuzzy match) before the folder rules and return shape. The quoted example prompts cost some length but earn their place by demonstrating the expected input style; no sentence is pure filler.

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

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

No output schema exists, and the description compensates by describing the return value (`found` with id/name/folder, or null) and the fuzzy-match contract. Combined with annotations covering safety, an agent has what it needs to call this correctly, though the relationship to sibling lookup tools remains unstated.

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 goes further on `prompt`, explaining the fuzzy-match/no-spelling-required behavior ('no spelling has to match', jev chooses), which the schema's terse 'in your own words' does not, and restates the folder scoping in matched terms.

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 clearly: resolve a freeform word-prompt to exactly one workbook by name, returning `found` or null. That verb+resource+cardinality (one-or-none) is unambiguous. It stops short of naming the sibling it differs from — find_folder for folders, search_workbooks/list_workbooks for broader listing — so differentiation is left to inference.

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 conveys usage indirectly through the phrasing advice ('Say it the way you would ask') and the folder scoping rules, which tells the agent this is a natural-language single-match lookup. But it never states when to prefer this over search_workbooks, list_workbooks, or find_folder, and names no 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context: nested sections are de-duplicated ('comes once, inside it'), a `missing` list reports headings no longer present, and 'no run starts' clarifies it is a pure read with no side effects.

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

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

The purpose is front-loaded, but several sentences are convoluted and dense ('Each of `sections` is as list_sections listed it plus `text`'), requiring re-reads. The content largely earns its place by describing an otherwise undocumented return shape, but the phrasing could be tighter.

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 no output schema, the description usefully explains the return structure: a `sections` array whose entries carry a heading line plus everything under it, nesting de-duplication, and a separate `missing` list. It is nearly complete for the tool's complexity, missing only error or pagination behavior.

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

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

Schema description coverage is 100%, so the `address` parameter is already documented by the schema; the description only reinforces that it comes from list_sections. The context and llm_model analytics params are self-describing in the schema, so the description adds little beyond the schema baseline.

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

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

The first sentence states a specific verb+resource (read sections named by an address) and ties it to the sibling that produces the address, list_sections. It distinguishes itself from the all-at-once read_workbook sibling by describing a 'focused part of the workbook instead of all of it,' though the prose is indirect enough that the core action takes some parsing.

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 implies the workflow by requiring an address that list_sections returned, giving usable sequencing context. However, it never states when to choose this over read_workbook, pick_section, or target_section, all of which appear as siblings, leaving the selection decision 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds value beyond them by disclosing that long text is truncated to the first 400 characters and that events are returned in execution order — a real behavioral constraint. It does not discuss failure modes for a missing/expired run id, which keeps it from a full 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?

It is front-loaded with the return shape and uses a single dense sentence plus one clarifying sentence on truncation, with no filler. It is a bit of a run-on enumeration, but each clause carries distinct information about a different event type.

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?

There is no output schema, so the description carries the burden of explaining what comes back, and it does so thoroughly: event kinds, their fields (node, ms, tokens, command, success, characters), and the truncation rule. Combined with annotations covering safety, an agent has everything needed to call and interpret it.

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 four parameters (including `run_id`, `workbook`, and the two analytics-only fields) are already documented in the schema. The description restates that run ids come from `list_runs`, matching the schema rather than adding syntax or format detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource — reconstructing everything one run did, in order — and enumerates the event kinds (`portal_returned`, `tool_returned`, `drafted`). It also distinguishes itself from the sibling `list_runs`, which only provides run ids. An agent can tell exactly what this tool produces without opening the schema.

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

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

It supplies the key prerequisite chain by naming `list_runs` as the source of run ids, which is real context for invoking the tool correctly. It stops short of explicit when-to-use / when-not guidance (e.g. use this for diagnosing a single run rather than enumerating runs), so it is strong context rather than full routing.

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

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

Goes far beyond the annotations: it discloses that runs and checkout_workbook pull the file first, that new versions are written back IN PLACE preserving sharing/revision history, format-specific handling for .xlsx/.docx, and the conflict case (a file changed mid-run is not overwritten; link.last_error reports it). Rich behavioral context that annotations alone (idempotent, openWorld) would never convey.

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

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

Front-loaded with the core purpose, then well-chunked bullets for the run/checkout and write-back behaviors. Length is substantial but the detail earns its place for a stateful linking operation; minor redundancy, but no wasted sentences.

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?

No output schema exists, and the description fully covers what an agent needs: seeding vs versioning on link, ongoing sync behavior, format handling, and the failure/conflict path. Nothing material is omitted for a tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already documents path, workbook, context, and llm_model. The description adds little about parameter meaning beyond the format examples already present in the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Makes a file ... the document of record for a workbook'), naming the exact scopes (Google Drive / Dropbox). An agent can distinguish this from unlink_workbook or create_workbook 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?

The description heavily conveys the consequences of linking, which implies when to call it, but never states explicit when-to-use conditions, prerequisites, or the alternative (unlink_workbook). Usage is inferable but not 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 already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world, so the safety profile is covered. The description adds real context beyond that — the path convention under which attachments are stored and cited, and that size is returned — but says nothing about ordering, pagination, or what happens for a workbook with no attachments.

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

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

A single sentence, front-loaded with the resource and its path convention, with no filler. The em-dash-heavy construction is slightly dense but every clause carries 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 simple read-only list tool whose safety profile is fully covered by annotations and which has no output schema, the description conveys the resource, the path convention, and the size field. Missing only minor details like ordering or empty-result behavior.

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

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

Schema description coverage is 100%, so all three parameters (context, workbook, llm_model) are already documented in the schema. The description adds no syntax or format detail beyond the schema's 'workbook id', 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?

The description names a specific resource — the files attached to a workbook — and goes further by giving the path form '/attachments/<workbook>/<name>' and noting the return includes each file's size. It is a noun-phrase fragment rather than an explicit verb+resource, and it does not explicitly differentiate from siblings like add_attachment/remove_attachment, but the resource is unmistakable.

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

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

There is no when-to-use guidance, no condition that selects this tool over add_attachment/remove_attachment, and no prerequisites or exclusions. The mention of what runs read and cite is descriptive context about the resource, not usage routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine context beyond them: the return format, per-folder workbook counts, a root-level count, and the important non-recursive semantics emphasized by 'DIRECTLY'. It does not mention pagination or ordering, but it is substantive for a read 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?

A single sentence, front-loaded with the resource, with no filler. The 'DIRECTLY' emphasis is the one piece of typographic weight and it earns its place by disambiguating the count semantics.

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

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

For a read-only list tool with no output schema, the description adequately explains what comes back, which is what an agent needs. It could add a word on how folders are ordered or whether empty folders appear, but nothing essential is missing given the annotations cover safety.

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

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

The two parameters (`context`, `llm_model`) are analytics-only metadata fully documented at 100% schema coverage, so the schema carries the load. The description adds nothing about parameters because none affect behavior. 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 (list the account's folders) and goes further by describing the output shape (paths like `Clients/Sagamore`) and the counts returned. An agent can distinguish it from `list_workbooks` and `find_folder` by the fact that it enumerates folders. It stops short of naming the sibling it should be chosen over.

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

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

The description implies usage by scoping the tool to the full set of account folders, which suggests enumeration/overview scenarios. However it never states when to prefer this over `find_folder` or how it relates to `list_workbooks`, nor any exclusions. Usage is inferable but not stated.

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 the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description adds real value beyond them: ordering (newest first), the returned dimensions (time, outcome, cost), and the status vocabulary (running, done, failed, cancelled).

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 lean sentences, newest-first ordering and the list-vs-single distinction front-loaded, and no filler whatsoever.

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

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

For a read-only list tool whose annotations carry the safety profile and whose parameters are fully described in the schema, the description tells the agent what it will get back. No output schema means return shape falls to the description, which it handles adequately via the outcome/status fields.

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 `run_id` and `limit` semantics are already documented in the schema. The description's contribution — that `run_id` yields a single run's current state and that status resolves to four values — is modest, 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?

The description names the resource (a workbook's runs) and the exact content returned (when each ran, how it ended, cost), plus the single-run mode. Combined with the title it is unmistakably a listing tool, distinguishable from stop_run. It lacks an explicit verb in the description body, relying on the title to anchor intent.

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 implies two modes — omit `run_id` to list, supply it to get one run's status — but never states when to prefer this over siblings like get_trace or stop_run. Usage is inferable rather than explicit, fitting the 'implied usage' tier.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: `address` is stable ('the same set always has the same address'), `address` is null when nothing is kept, kept sections carry a `probability` share, and 'Reads only; no run starts.' These are meaningful traits not present in 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?

No sentence is pure filler, and the field enumeration is front-loaded. But the delivery is one long, comma-spliced run-on that is hard to parse, and the return-field detail is interleaved with the filtering behavior. Readability suffers relative to its information density.

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?

There is no output schema, so the description carries the burden of describing return shape — and it does, enumerating heading, path, value (with its kinds), level, sheet, line and address. Combined with the annotations, an agent has enough to call and interpret the tool. It could be slightly stronger on how the listed set relates to follow-up calls.

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 and the structured fields already document each parameter. The description still adds value by elaborating the semantics of `prompt` — how jev weighs headings against one another and returns `probability` shares — which goes beyond the schema's one-line gloss. It says nothing extra about sheet/context/llm_model, but those are adequately defined in the schema.

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

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

The description states a concrete verb+resource (lists a workbook's sections) and enumerates the fields each section carries, so the agent knows what comes back. It also implicitly distinguishes itself from get_sections by noting the returned `address` is what get_sections reads. It stops short of a clean one-line purpose statement because the prose is dense and buries the core action.

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 two operating modes clearly — omit `prompt` to list every heading, give `prompt` to have jev weigh headings and keep a relevant subset. That is genuine contextual guidance for the primary parameter. However it never states when to choose this tool over the many other navigation siblings (pick_section, target_section, read_workbook), so tool selection 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 carry the read-only/idempotent/non-destructive profile, so the bar is lower, yet the description adds real value by defining each `state` value (editing, needs_input, stale, fresh, idle) and noting the id contract with other tools. It goes beyond the structured fields rather than restating them.

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

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

It is dense but front-loaded with the returned fields, and every sentence (field list, state definitions, id contract) earns its place. The state enumeration is slightly list-heavy but stays within a reasonable size.

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 no output schema, the description correctly takes on the burden of describing return values (title, asked, folder, version, last-changed, state) and does so thoroughly. Only the analytics/pagination behavior is left unspecified, a minor 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 description coverage is 100%, so the schema already documents all three params. The description adds no syntax or semantics for `folder` (e.g. recursive behavior) or the context/llm_model analytics params, so baseline 3 applies.

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

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

The description states a specific verb+resource ('every workbook this account has') and enumerates the returned fields, so the scope is unambiguous. It implicitly contrasts with search/find siblings by saying 'every workbook,' but never names them to differentiate explicitly.

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 implied ('Every workbook this account has' suggests a bulk listing) and the final sentence explains that ids feed other tools, which hints at when to reach for it. However there is no explicit when-to-use vs alternatives (e.g. search_workbooks, find_workbook) or any exclusion condition.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds real behavioral context beyond them: implicit creation of all parent folders, an explicit character blacklist, and a six-level nesting cap. It stops short of stating what happens when the folder already exists or what errors are returned on invalid names.

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

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

Two tight sentences, front-loaded with the core behavior and the concrete 'Clients/Sagamore/2026' example that makes the recursion unambiguous. No filler.

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

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

For a mutation tool with no output schema, the description supplies the key operational facts (recursive creation, naming rules, depth cap) that an agent needs to call it correctly. Missing only edge-case behavior such as idempotency on existing paths and permission requirements, which is a minor gap given the annotation coverage.

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 genuinely enriches the path parameter with validation semantics the schema lacks — forbidden characters (/ \ : * ? " < > |) and the six-level depth limit. The context and llm_model params are fully documented in the schema as analytics-only, so no description support is needed there.

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

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

The description opens with a precise verb+resource ('Creates a folder') and immediately adds the distinctive recursive scope ('and every folder above it'), which cleanly separates it from sibling folder tools like find_folder, rename_folder, and remove_folder. An agent knows exactly what this tool produces 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 states constraints but never says when to reach for this tool versus alternatives, nor any prerequisites or whether it should be called before uploading/moving workbooks into the folder. Usage is only inferable from the tool name.

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 idempotent=true, destructiveHint=false, and readOnlyHint=false, so safety is covered. The description adds value beyond that by disclosing that the target folder is auto-created when missing, that an empty path resolves to the root, and that document content is untouched — behavior the agent cannot infer from annotations alone.

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

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

Three short sentences, all front-loaded with the core verb first, then edge-case behavior, then scope limits. No filler and every clause carries information an agent needs.

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 idempotent, non-destructive move operation with full schema coverage and no output schema, the description covers the key edge cases (auto-create folder, root placement, document immutability). It does not discuss what happens on a missing/invalid workbook id or the return value, but those gaps are minor given the 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 100%, so the schema already documents folder ("Empty for the root"), workbook, context, and llm_model. The description's root-path note merely restates the folder parameter's schema text, so it does not add meaning beyond structured data. Baseline 3 applies.

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

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

The description opens with a specific verb+resource ("Moves one workbook") and immediately scopes the operation with "This moves the workbook only — nothing about the document changes," which separates it from sibling operations like rename_folder or linked-document tools. An agent can identify the operation 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 implies usage through behavior ("An empty path moves it to the root"), but it never states when to choose this tool over siblings like find_workbook, make_folder, or list_folders. The implicit context is clear enough for a placement operation, but no alternatives or prerequisites are named.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds 'Reads only; no run starts' plus a full account of the return contract: what `section` contains, what `confidence` and `considered` mean, and that `section` is null when nothing matches. With no output schema present, this return-value disclosure carries real weight.

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 in the first clause, followed by mechanics, return shape, and the list-headings mode. The em-dash-heavy sentences are dense but each carries substantive information; only minor trimming is possible.

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 no output schema, no enums, and five params, the description covers purpose, input semantics, the alternate no-prompt mode, and the full return shape including the null case. It is complete enough to call correctly; the only gap is explicit comparison against sibling section tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by giving concrete `prompt` examples ('ATH434 in multiple system atrophy', 'the competitive landscape') that illustrate the intended natural-language phrasing. It does not clarify `sheet`, `context`, `llm_model`, but those are self-documented.

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: it selects the prose section under a heading, matched from the caller's own description rather than a known heading name. The mechanism ('chosen from every heading in the workbook, as the document has them') is precise enough to distinguish it from tools that list or target sections, though it never names those siblings explicitly.

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

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

It gives clear triggering context — use when you can describe what you want but do not know a heading ('you do not need to know a heading') — and states an alternative mode within the tool ('Omit `prompt` to list the headings instead'). It stops short of routing the agent against sibling tools like get_sections, list_sections or target_section.

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, idempotent and non-destructive safety, yet the description adds genuinely new behavior: the null-table fallback when nothing matches, the presence of a `considered` ranking and `confidence` score, citation resolution, and that no run starts. 'Reads only' partly restates readOnlyHint, which keeps it from 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 core purpose and prompt semantics are front-loaded, and every sentence (output shape, null case, listing mode, read-only) carries information. The em-dash-heavy prose is dense and slightly run-on, but it is appropriately sized for the tool's complexity.

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

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

With six parameters and no output schema, the description carries the return-value burden and does so fully: it describes `table` (columns, rows, citations, confidence), `considered`, the null case, and the alternate listing output. Nothing an agent needs to invoke and interpret it 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; the description goes beyond it by explaining `prompt` as free-form natural language with examples and by spelling out that omitting it switches the tool to a listing mode. It adds no meaning for `sheet`, `version`, `context` or `llm_model`, which the schema already documents.

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

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

The description states a specific verb and resource ('One table from a workbook as data, chosen from your own words') and defines the selection mechanism (semantic match over headings). It is clearly distinguishable from siblings like pick_section and read_workbook 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 gives clear context for use ('say what you want in prompt... you do not need to know a heading') and a secondary mode ('Omit prompt to list the tables instead'), plus recovery advice when no match is found. It stops short of explicitly naming alternative sibling tools such as pick_section for the same job, so it is clear but not fully routing.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, open-world behavior. The description adds real value beyond them by disclosing the conditional mutation ('writes it in as a new version if its content changed'), which explains both why it mutates and why it is idempotent. It does not mention permissions or rate limits.

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

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

A single front-loaded sentence with an em-dash clause for the usage scenario; every clause earns its place and nothing is padded. Slightly dense but well organized.

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 no output schema, the description still conveys the action, the conditional write behavior, and the trigger scenario, and annotations cover safety semantics. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (including the analytics-only context and llm_model). The description adds no parameter-level detail, 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+resource: reads a linked workbook's file from the drive and writes it in as a new version if changed. This clearly separates it from read_workbook (plain read) and link_workbook (creates the link). It does not explicitly name a sibling, but the 'now rather than at the next run' framing disambiguates from scheduled pulls.

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

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

Provides a concrete usage trigger: 'for after somebody has saved it in Excel or Word,' and contrasts immediate pull vs. 'at the next run.' No explicit exclusions or named alternative tools, but the context is clear enough to select correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral value by detailing the return contents (tabs with sizes, sources, the posed question, version history, and question/answer runs), which substitutes for the absent output schema.

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 content is front-loaded with the core ('The current document as markdown'), but it is delivered as one long run-on sentence with nested parentheticals that would benefit from partitioning into return-shape vs. parameter notes.

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

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

For a read tool with full annotation coverage and no output schema, the description does the heavy lifting of describing the return payload and versioning behavior. It is largely complete, with the only gap being the absence of alternative-tool routing.

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 usefully links the returned `tabs` field to the `sheet` parameter, but adds little for `version`, `workbook`, `context`, or `llm_model` beyond what the schema already states.

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

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

The description clearly states the resource (the current workbook document rendered as markdown) and enumerates what it contains — tabs, version, sources, question, prior versions, and messages. It's a specific read operation, though it never explicitly contrasts itself with close siblings like list_workbooks, pull_workbook, or render_document.

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

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

There is a hint that passing a tab's id as `sheet` reads just that tab, but no explicit when-to-use, when-not, or alternative routing. With many sibling tools for reading/locating workbooks, the agent gets no guidance on when this one is the right call.

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

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

The description adds real behavior beyond the annotations: a concurrency precondition (refused while a run is editing) and an explicit scope limit (reads sources, does not change the document). It also implies an open-world re-fetch against external sources, matching openWorldHint=true, though it says nothing about cost, latency, or what a stale fingerprint looks like.

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 core action and output, then the refusal precondition, then the read-only clarification. Every sentence carries distinct information and none repeats the name or title.

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

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

With no output schema, the description carries the return-value burden and does state the shape of the answer ('what has moved'), plus the gating condition. It is slightly thin on how drift is reported (per-source listing? summary?) and on what happens if the tool is refused.

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 three parameters (workbook, context, llm_model) are already fully documented in the schema. The description adds no parameter-level detail such as which version 'current' refers to or how workbook IDs are obtained, 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 ('Re-fingerprints every source the current version cites') plus the answer it produces ('what has moved'). The closing contrast ('does not change the document') separates it from write-side siblings such as save_sources and commit_workbook without needing their schemas.

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

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

Usage is only implied: you call it to learn whether cited sources have drifted. The only stated condition is the negative precondition ('Refused while a run is editing the workbook'), which is a constraint rather than when-to-use guidance, and no alternative tool (e.g. workbook_sources, save_sources) is named for comparison.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description contributes one extra fact — the removal persists into later runs — but says nothing about reversibility, permissions, or whether the underlying file is deleted.

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, zero filler, with the action front-loaded ahead of the consequence. Nothing could be cut without losing meaning.

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

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

For a destructive-but-idempotent tool with no output schema, the annotations plus description give an adequate picture, but routing among siblings (restore_version, unlink_workbook) and the scope of the deletion are left unspecified. It is minimally sufficient rather than complete.

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

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

Schema coverage is 100%, so 'name' and 'workbook' are fully documented in the schema and the description merely restates them. The two analytics-only parameters (context, llm_model) carry their own detailed schema descriptions, so no 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 ('takes one attached file off a workbook') and scopes it to a single file. It is clearly distinct from add_attachment, though it does not name the sibling explicitly.

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 only implied by the counterpart name add_attachment; there is no explicit statement of when to call this versus restoring a version or unlinking. 'Later runs no longer see it' hints at effect but not at selection conditions.

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, idempotentHint=true, and readOnlyHint=false, yet the description adds genuinely new and consequential semantics: deletion is recursive into subfolders, contained workbooks are reparented to the parent folder rather than deleted, and no sibling tool deletes a workbook. That is exactly the cascade/containment context an agent cannot get from annotations.

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

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

Three short sentences, front-loaded with the core action and scope, then the non-obvious preservation behavior. No filler and nothing repeated from the schema.

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

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

With a fully covered schema and annotations carrying the safety profile, the description supplies the key missing piece: cascade scope and the fate of contained workbooks. It omits error behavior (e.g., nonexistent path) and permission requirements, which are minor gaps for a no-output-schema mutation 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 all three parameters (including the injected context and llm_model analytics fields) are fully documented in the schema. The description adds no syntax, format, or constraint detail for 'path' beyond what the schema says, so 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 ('Removes a folder') and immediately extends to scope by noting it removes the folders under it. This clearly distinguishes it from siblings like make_folder, rename_folder, and move_workbook.

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

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

The description implies when to use it (removing a folder) and preempts a likely concern by explaining workbooks survive, but it names no alternatives and gives no explicit when-not-to-use guidance or prerequisites.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely useful behavior beyond that: the rename cascades to all contained folders and workbooks, nothing is lost, and no references are left dangling. It still omits conflict handling (e.g., an existing target name) and permission requirements.

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

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

Two short, front-loaded sentences that lead with the operation and then the cascade effect. The second sentence is slightly redundant, restating the same 'nothing lost / nothing dangling' idea twice, which keeps it from a 5.

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

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

For a mutation tool with no output schema, the description covers the essential behavioral consequence (contents move with the folder) and annotations cover safety. It stops short of addressing conflict cases or authorization, but is otherwise sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the analytics-only 'context' and 'llm_model'. The description adds no syntax, format, or constraint detail beyond the schema, so the baseline of 3 is correct.

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 ('Renames a folder') and adds scope by noting it carries every nested folder and workbook with it, which distinguishes it from sibling mutations like move_workbook or make_folder. It does not explicitly name a sibling it is not, so it falls short of 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?

Usage is only implied by the operation name; there is no explicit guidance on when to rename versus alternatives such as make_folder, move_workbook, or remove_folder. No prerequisites, no when-not conditions, and no alternative routing are provided.

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 substantial behavior beyond the annotations: the link lasts about six days, the PDF is stored in the account's own storage, the first compile of a rarely used package can take a minute, and compiler error messages are returned verbatim with the failing line. These are all actionable facts an agent needs that the annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true) do not convey.

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

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

The core action and output lead the paragraph, then format-specific detail follows in order. Every sentence carries operational weight (engine caveats, minted/biber limits, error behavior); nothing is filler despite the length, which is justified by three supported formats.

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 no output schema, the description still explains the return value (a link, ~six-day lifetime) and failure mode (compiler message with failing line). Combined with format constraints and asset handling, an agent has everything needed to call this correctly, even at 7 parameters.

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 genuine meaning about how parameters interact: the main .tex goes in `source`, the rest of the project (chapters, refs.bib, .cls) goes in `files`, and images may be supplied either as base64 inside `files` or via `assets` URLs. That clarifies the files-vs-assets split beyond 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?

States a specific verb (compiles/renders), the resource (a document in LaTeX, Typst or Markdown), the output artifact (a PDF filed in account storage) and the return value (an openable link). An agent can instantly tell this apart from the workbook-centric siblings.

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

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

Gives clear per-format context so the agent knows which value to pass: latex is real TeX with Tectonic, typst is a complete Typst document, markdown is a clean report style. It also states constraints (shell escape off, biber unavailable) that steer the agent toward valid inputs. No explicit exclusions are needed since no sibling performs a comparable compile.

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 readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the restore creates a new version and the replaced version is preserved and can itself be restored, which tells the agent the operation is history-preserving rather than an overwrite.

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

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

Two tight sentences with zero filler; the core effect is front-loaded and the history-preservation detail and version-source pointer follow in priority order.

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

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

For a mutation with no output schema and full schema coverage, the description covers effect, reversibility, and parameter sourcing, which is nearly everything an agent needs. It could add a note on whether other collaborators see the restored version, but nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns an extra point by explaining where `version` values come from (read_workbook's `versions`), which the schema itself does not convey.

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

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

States a specific verb and resource ('Makes an earlier version of a workbook its current one again') and clarifies the resulting state ('as a new version'). This clearly separates it from write_workbook, commit_workbook, and checkout_workbook among the siblings.

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

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

Gives clear context for use and points to read_workbook's `versions` as the source of valid version identifiers. It does not state explicit when-not conditions or name a competing sibling to prefer instead, so it stops 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 the annotations (idempotentHint, destructiveHint=false) by disclosing the destination folder, the idempotent no-double-copy behavior on re-invocation, the two-minute timeout with a remaining count, the refusal while a run is editing, and the fact that nothing is billed.

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 dense sentences that front-load the core action and then stack behavioral facts (skip logic, return payload, timeout/continuation, refusal, billing). Slightly packed, but every clause 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?

Despite no output schema, the description explains the return payload (drive and folder, written/skipped counts, failures, remaining count). Combined with annotations and full schema coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the schema already documents workbook, context, and llm_model, including the context privacy constraints. The description adds no additional parameter-level detail, so 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 (Copies) plus resource (every web source the current version cites) and destination (account's connected drive, in the workbook's subject folder), and anchors it to a known app action ('the same as Save to Dropbox in the app'). This is clearly distinguishable from sibling workbook_sources and recheck_sources.

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 specifies meaningful conditions: it only copies web sources (files already on a drive are left alone), it is refused while a run is editing the workbook, and calling again continues a timed-out run. It doesn't explicitly name sibling alternatives, but the conditions cover when the tool applies and when it is blocked.

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 read-only, idempotent, non-destructive behavior, so safety needs no restating. The description adds genuine behavioral context beyond them: snippet generation around the first match and a deterministic ranking (title matches first, then prompt, then most recently changed). It omits any result-count cap or pagination behavior, keeping it just 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?

Two sentences, well front-loaded: matching semantics and ranking lead, with the example phrase last. Efficient overall, though the 'tea importers'/'weekly ops' example partially duplicates the example already in the query parameter's schema description, so it does not fully earn 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?

With no output schema, the description carries the return-shape burden and does so adequately: a matching set with snippets and a defined order. It does not address result limits, empty-result behavior, or whether all matches are returned, which is a minor gap for a search 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 the baseline is 3, and the description earns above that by elaborating the `query` semantics the schema only gestures at: all words must appear, any order, case-insensitive, phrases resolved to named workbooks. The context/llm_model params are fully documented in-schema and need no further prose.

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 (search) and resource (workbooks), and precisely defines what is searched (title, latest prompt, current text) and how matching works (every word, any order, case-insensitive). This is enough to distinguish it from find_workbook and list_workbooks without opening a sibling schema.

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

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

Usage is implied by the phrase-search semantics ('a phrase such as tea importers finds the workbook it names'), which suggests when it beats name lookup. However it never explicitly contrasts with find_workbook or list_workbooks, nor states when NOT to use it. Adequate but leaves the routing decision 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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false; the description goes beyond them by disclosing that rotate makes a new link and 'stops the old from opening,' and that making or widening a link publishes the workbook and warrants user confirmation. It does not cover permission/auth requirements for the caller or what happens when create is called on an already-shared workbook, which keeps it from 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?

Content is front-loaded: the share-link concept comes first, then the actions, then visibility, then the safety caveat. It is one dense paragraph with em-dash clauses, but no sentence is filler; the only criticism is that the clause density makes it slightly heavy to scan.

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

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

With no output schema, the description usefully states what 'show' returns ('says whether it is shared and gives the link') and warns about the publishing side effect of create/visibility changes. For a 5-parameter tool with two enum parameters, this is close to complete; only edge-case behavior (calling create when already shared, error conditions) is 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 the baseline is 3, but the prose adds real meaning beyond the terse schema text: it explains rotate's effect on the prior link and both visibility enum values ('link' = anyone holding it reads; 'members' = only members, after proving their email). The analytics-only params (context, llm_model) are correctly left to their verbose schema entries.

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

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

The description states the resource precisely ('A workbook's share link: a URL that always opens its current version, with its sources') and enumerates the three actions (show/create/rotate), so the agent knows exactly what the tool operates on. It does not, however, differentiate itself from confusable siblings such as link_workbook or unlink_workbook, which is the only gap in an otherwise sharp statement of purpose.

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

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

It gives per-action when-to-use guidance: 'show' is the default that reports share state, 'create' makes a link, and 'rotate' is explicitly for 'a link that reached someone it should not have.' It also adds a procedural rule, 'confirm with the user,' before publishing. No alternative tool is named, so it stops short of full explicit 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?

With annotations already declaring non-readOnly, non-destructive, idempotent behavior, the description still adds substantial context: the run stops at once, partial writes become a new unfinished version with the prior version kept restorable, no version is written if nothing changed, and drawn procedures write nothing. This is exactly the kind of preservation semantics the 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?

Front-loaded with the purpose in the first clause, then dense behavioral detail where every sentence carries distinct information (immediate stop, version creation, no-op case). It is on the longer side 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 mutation tool with no output schema, the description fully covers the state transitions an agent needs to reason about — what happens to written content, versioning, and the no-run case. Nothing material is missing.

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

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

Schema description coverage is 100%, so run_id, workbook, context, and llm_model are all already documented in the schema. The description adds only a restatement of the run_id-vs-live-run default, which the schema itself states, so 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 ("Stops the run editing a workbook") and immediately scopes which run via the `live_run` field that read_workbook exposes or a named `run_id`. An agent can distinguish this from list_runs/read_workbook/restore_version 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 how to target the run (the workbook's live run or a named run_id) and describes the edge case where no run is going. It gives clear context for invocation but never names a sibling alternative or an explicit when-not-to-use condition.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the closing 'Reads only; it makes no change' largely restates that. The real added value is behavioral: the selection algorithm (weighs sections against each other, prefers sections in hand, prefers inner sections over containers), the given/rest distinction, and the cost signal implied by `rounds` and `asked`. No auth or rate-limit details are given, but the algorithmic disclosure goes well beyond the annotations.

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

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

The purpose is front-loaded in the first sentence, which is good. However, the remainder is a dense, run-on block packing the algorithm, return shape, and edge cases into comma-spliced clauses that are hard to parse. Almost every sentence earns its place informationally, but readability and structure suffer.

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?

There is no output schema, so the description carries the return-value burden — and it does, enumerating `sections` fields (workbook, from, probability, text), `workbooks` counts, `matched` states, and `unknown`/`rounds`/`asked`. Combined with the read-only guarantee and the selection algorithm, an agent has enough to call and interpret it, though permission/auth context is absent.

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

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

Schema description coverage is 100%, so the schema already documents prompt, targets, address, section, and workbook — the baseline here is 3. The description adds concrete prompt examples and clarifies that `section` may be a path or a heading only one section has, which is useful but largely mirrors what the schema already states. Marginal added meaning over structured fields.

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

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

The opening line — 'Every section an edit changes, in every workbook it changes' — states a specific resource and scope, and the tool is clearly distinct from list_sections/pick_section (it references list_sections as the source of addresses rather than competing with it). The core purpose is recoverable, but the phrasing is a noun fragment rather than a clean verb+resource, and the middle of the description obscures the simple idea that it maps an edit to affected sections.

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 shows how to call it (give an edit as `prompt` and sections in hand as `targets`) and even gives worked prompt examples, so usage is implied. But it never states when to use this tool instead of list_sections, get_sections, or pick_section, nor any preconditions or exclusions. Context is inferable but no explicit when/when-not guidance is present.

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 destructiveHint=false and idempotentHint=true, and the description reinforces this by explicitly stating 'Nothing is deleted: the workbook keeps every version, and the file stays in the drive as it is.' This is valuable non-obvious reassurance about a mutating operation. It does not describe auth requirements or side effects beyond data retention.

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 immediately followed by the key clarification that nothing is deleted. No filler, every clause 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 single-resource mutation with no output schema and full schema coverage, this gives the agent the essential facts: the operation is non-destructive and reversible in the sense that versions and the file remain. It omits whether the link can be re-established (link_workbook) or permission requirements, but is largely complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the params (context, workbook, llm_model) are already documented in the schema. The description adds no parameter-specific semantics beyond the fact that this acts on a workbook's linked file. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific action ('stops bringing a workbook's linked file in and writing versions back') on a clear resource. The title already names the operation, and the description elaborates the mechanism. It does not explicitly distinguish itself from siblings like link_workbook, but the noun pair ('linked file') makes the direction of the operation inferable.

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 usage context is implied: you use this when a workbook is currently linked and you want to stop that link. There is no explicit 'use this when...' or named alternative (e.g. link_workbook), so the agent must infer when it applies. No exclusions or prerequisites are stated.

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 cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) and the description layers on facts they don't carry: the run is billed to this account, takes minutes, returns a run id immediately without waiting, and the workbook reflects changes only when the run finishes. It also discloses the second, non-writing behavior for question-shaped instructions. No contradiction with destructiveHint=false.

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

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

Front-loaded with the core action, and every sentence carries distinct information (billing, latency, async return, question fallback). It leans toward long run-on clauses and buries the read_workbook cross-reference at the end, but there is no filler.

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

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

For a 6-parameter mutation tool with no output schema, the description supply enough: it says what comes back (a run id) and that it does not block. It stops short of telling the agent how to track completion (list_runs, get_trace, stop_run exist as siblings), which is the main remaining 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 description coverage is 100%, so the baseline is 3, and the mode enum's rich semantics live in the schema rather than the description. The description does add the example instruction shape and reiterates that a latticeroom instruction is a whole draft, but that is marginal value over the schema.

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

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

The description names a specific verb and resource — 'Starts a run on the workbook' — and pins the input form ('one sentence the way a person would say it') with concrete examples. It also carves out the question-shaped instruction case and routes the answer to read_workbook's `messages`, which distinguishes it from the read-side sibling.

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

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

It gives clear usage context and examples ('add a section on Q3 headcount', 'refresh the cash figures'), plus an explicit when-not path for questions. What's missing is any mention of the sibling write paths (write_workbook, commit_workbook) so the agent can tell a direct edit from a run.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and a closed world, so safety is covered. The description adds content semantics and the newest-first ordering, but says nothing about pagination, result size, or empty/absent notes, so it adds only modestly beyond the structured fields.

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 compact sentences with no redundancy, and the subject (the notes) is front-loaded. The phrasing is slightly indirect and literary, but nothing is wasted.

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

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

For a read-only, no-output-schema tool with fully documented parameters and annotations covering its safety profile, the description communicates enough to call it correctly. It falls short of 5 only because sibling differentiation and usage conditions are not spelled out.

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 three parameters (workbook, context, llm_model) are already documented in the schema. The description adds no parameter-level detail, 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 names a specific resource (notes a workbook's runs have kept) and what it shows, with concrete content examples ('preferences, corrections, where things are'). It is clear what the tool returns, though it does not explicitly distinguish itself from siblings like read_workbook or get_trace, so it stays below 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?

It hints at usage context ('Runs read them; this shows them') by contrasting the internal consumer with the caller. However, it gives no explicit when-to-use, when-not-to-use, or named alternative among the many workbook siblings, leaving selection guidance implied.

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

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

The annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuinely useful behavior beyond that: it disambiguates the empty-list case (nothing moved vs. never checked) and explains that checked_ms of 0 signals the latter, which an agent could not infer from structured fields alone.

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

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

Two sentences with no filler; the core scoping condition is front-loaded and the empty-list caveat follows immediately. 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?

With no output schema, the description carries the burden of explaining returns and does so partially — it describes the list contents and the checked_ms semantics. It could say more about what each citation entry contains, but for a read-only query tool it is close to complete.

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

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

Schema description coverage is 100%, so workbook, context, and llm_model are fully documented in the schema itself. The description adds no syntax or format detail beyond that, 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 identifies a specific resource and scope: the citations of the current version whose sources have changed, plus their last-checked times. It is distinguishable from siblings like recheck_sources or save_sources, though it never states an explicit verb such as 'returns' or 'lists' — the retrieval action is only implied.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternative (recheck_sources) for refreshing stale sources. The interpretation hint about empty lists is about reading results, not about when to invoke the tool.

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

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

Annotations only give the safety profile (readOnly=false, destructive=false, idempotent=false); the description goes far beyond, disclosing the versioning model (every write is a new version, the prior one is kept and restorable), the refusal conditions (workbook moved past base_version or a run is writing it), and that there is no charge. This is exactly the extra behavioral 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?

Front-loaded with the core action and cost, then the required inputs and semantics; every sentence carries weight. The nested sheets parenthetical is dense and somewhat hard to parse in one pass, which is a minor structural cost rather than filler.

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

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

For a 7-parameter mutation tool with no output schema, the description covers the operation, the two required inputs, the document/sheets exclusivity, tab semantics, versioning, and refusal cases. The remaining analytics params (context, llm_model) are self-documented in the schema, so nothing an agent needs to call 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 baseline is 3, but the description substantially exceeds it by explaining the sheets combination logic that the schema only lists field-by-field: {id} alone keeps a tab unchanged, {id, markdown}/{id, name} replaces, {name, markdown} with no id adds, and omission removes a tab, plus the EXACTLY-ONE-of document/sheets constraint. This adds real invocation meaning beyond the schema.

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

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

States a specific verb and resource ('Writes a new version of a workbook') and immediately scopes it against the run-based path with 'with no run and no charge.' Combined with the versioned-write framing, an agent can distinguish it from commit_workbook/update_workbook without opening 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 clear prerequisites and workflow context: send 'base_version — the version you read,' implying read_workbook is the precursor, and 'no run and no charge' signals it is the non-execution alternative. However, it never names a sibling tool or states an explicit when-not condition beyond the refusal cases, so it stops 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.