Skeletable

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

Annotations already cover the mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds two things not in structured data: an auth requirement ("Needs a token") and the return payload (new column ids). It stops short of mentioning limits such as the 20-column cap or what happens to existing columns.

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

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

Three short sentences, front-loaded with the action and followed by return value and auth need. Every sentence carries weight; only the slightly awkward "such as a blank one a person started" phrasing costs a point.

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 annotations covering safety and no output schema, the description covers auth, return value, and workflow placement, which is decent. It leaves the `slug` identifier and the column-count constraint unexplained, gaps an agent would hit on first call.

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 top-level `slug` parameter is undocumented in both the schema and the description — the phrase "a draft you run" only weakly implies it identifies the draft. The nested column properties (rule, type, choices, instruction) are well described in the schema, but the description itself adds nothing about which parameters to supply or how.

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

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

States a specific verb and resource ("Add columns") and scopes it to "a draft you run, such as a blank one a person started," which distinguishes it from create_table or add_rows. It also names the downstream consumer (fill_cells), so the agent can place it in the workflow.

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?

"Returns the new column ids for fill_cells" implies the next step in the sequence, and "such as a blank one a person started" implies when it applies. There is no explicit when-not or a named alternative to prefer over this tool, so usage is implied rather than 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?

Goes well beyond the annotations by disclosing upsert semantics (an existing name receives the given values, so re-syncing is one call), key auto-assignment for keyless rows, skip behavior for value-less duplicates, the 500-row cap, table-state restrictions, and the token requirement. Note a mild tension with idempotentHint=false: the description implies re-sync is safe, but keyless rows still append on each call — it is not a real contradiction because keyed rows behave differently from anonymous ones.

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 row limit, then layers dedup, provenance, and table-state rules in a logical order. It is dense and somewhat run-on in the middle, but almost every clause carries operational meaning.

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

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

Covers the write semantics, constraints, and auth that matter for a 2-parameter bulk mutation, which is a lot given the zero schema coverage. It does not say what the call returns (created vs updated counts), and there is no output schema to fill that 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?

With 0% schema description coverage the description carries the load and mostly succeeds: it explains that `rows` accepts plain names or objects with `values` keyed by column id or label, defines `key`, and spells out the `origin` enum with its `note`/`source` companions and default. The `slug` parameter is only implied ('a table you run') and never explicitly described.

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

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

Opens with a concrete verb+resource+bound: 'Add up to 500 rows to a table you run,' which immediately separates it from cell-level siblings like fill_cells or get_cell. It never names a sibling explicitly, so the differentiation is inferred rather than stated.

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

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

Gives clear usage context ('so a whole tracker or dataset goes in a few calls') and concrete preconditions: rows with values can go into published tables, name-only rows only into drafts, and proof-required tables accept name-only rows. It stops short of explicitly routing an agent away from alternatives such as fill_cells when only individual cells need updating.

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, but the description adds the verdict taxonomy (matches, differs, disputed, unknown) and which extra fields accompany them, plus a real limitation: it compares values and does not judge meaning. That is valuable context annotations cannot supply; it stops short of saying how comparison normalizes whitespace/case or whether missing cells error.

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 action, then the verdict semantics, then the caveat, then the prerequisite. Every sentence carries information, though the parenthetical asides ('so say so', 'with what the source states') make it slightly denser than needed.

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

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

With no output schema, the description carries the burden of explaining return values and does so via the four verdicts and the `conflicts` reference. The remaining gap is comparison rules (normalization, what `differs` quotes look like) for a tool whose entire purpose is value comparison.

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 each parameter documented inline including its provenance (row from get_table, slug from list_tables). The description adds no syntax or format detail beyond the schema, 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 — 'Test a statement against one cell' — and illustrates with a concrete scenario (a draft or an answer). It implicitly separates itself from the read-only sibling get_cell and from fill_cells, though it never explicitly contrasts with them.

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 prerequisite workflow: 'Use list_tables and get_table to find the cell first', and cautions to 'read the quote before relying on a text verdict'. It does not name an alternative tool to use instead when the agent only wants to read a value (get_cell).

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 context beyond annotations: it discloses the token requirement (auth), that the table is a private draft, that a person must supply missing fields before publishing, and that it returns column ids and a link. With annotations covering safety, this is exactly the extra behavioral detail an agent needs.

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

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

Front-loaded with purpose and required-vs-optional params, then return values. Dense and mostly every sentence earns its place, though the 'tell your person to open it' aside is minor flourish.

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 non-idempotent, open-world mutation tool with no output schema, the description covers creation semantics, auth, downstream prerequisites, and return contents. An agent has enough to call it and hand off 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 baseline is 3; the description adds real meaning on top by explaining proof's default and required-mode behavior and that template changes which fields are required. It reinforces rather than merely repeats 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 ('Make a private draft table') plus scope ('anything from a tracker to a dataset'), and distinguishes it from the fill/export/get siblings by framing it as the creation step. An agent can tell this apart from add_columns or fill_cells immediately.

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 which params are required now vs. optionally useful ('Only title, columns and rows are needed now, but give question, scope, and a rule if you can') and points forward to fill_cells for the next step. It does not give explicit when-not-to-use or alternative-route guidance, but the workflow context is clear.

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

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

Beyond the annotations, the description discloses the security model ('Anyone with the link can read the data'), the auth requirement ('Needs a token'), and the non-obvious consequence of `fresh` ('the old one stops working'). That link-invalidation behavior goes meaningfully past idempotentHint=false and is exactly the kind of pre-call warning an agent needs; it sits in mild tension with destructiveHint=false only if read as data deletion, which it is not.

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 in the first clause and every subsequent sentence adds distinct information (query modifiers, sharing scope, `fresh`, token). The opening sentence is long and clause-stacked, 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?

With no output schema and no annotations covering safety, the description does decent work on sharing and auth. Gaps remain: it is unclear whether the tool returns the URL, the CSV, or the snippet lines ('with the lines to do it' suggests snippets but is ambiguous), and the identity of `slug` is undefined. For a 2-parameter mutation tool these are real but not fatal omissions.

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 0%, so the description must carry the parameter meaning. It explains `fresh` well, but `slug` — the required parameter — is never described; the agent must guess it is the table identifier. It also documents URL query modifiers (`?columns`, `?names`) that are not schema parameters, which is helpful but does not fill the `slug` gap.

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 makes clear this produces a private, token-bearing address that serves a table as CSV, with ready-made lines for notebooks, scripts, or spreadsheets. The resource and output are identifiable, but it never states a verb ('create'/'get a link') and never distinguishes itself from the sibling `export_table`, so an agent must infer the difference.

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 through consumer contexts (notebook, script, spreadsheet) and a prerequisite is given ('Needs a token'), which is useful. However, there is no explicit when-to-use guidance relative to `export_table` or `share`-style siblings, and no statement of when a shared link is inappropriate.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral detail about output shape: default row names, column ordering, proof mode adding source/quote/origin, and empty fields meaning no value. These details go beyond what annotations provide.

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

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

The description is compact, front-loaded, and every sentence adds relevant information about the output format or parameter effects. There is no wasted text.

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 does a good job explaining the CSV structure, default name column, column selection, proof mode, and empty field behavior. It could say more about encoding or exact formatting, but it is sufficient for an agent to call 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 description coverage is 100%, so the schema already documents all parameters well. The description adds marginal meaning, such as column order and the effect of proof mode on output layout, but much of it restates what the schema provides. A baseline 3 is appropriate when the schema carries most of the semantic load.

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

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

The description clearly states that the tool returns a table as CSV, ready to save or load into a notebook, which is a specific output and resource. It does not explicitly distinguish itself from siblings like get_table or list_tables, but the CSV export framing is clear enough for an agent to understand its purpose.

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

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

The description implies usage by saying the output is 'ready to save as a file or load into a notebook,' but it gives no explicit guidance on when to choose this tool over get_table or other siblings. The parameter explanations add context but not selection criteria.

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

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

Adds real context beyond the annotations: a hard 200-answer cap, per-answer partial failure with a returned reason (so the write is not all-or-nothing), values stored as generated along with the instruction and model, and an explicit token/auth requirement. Annotations already cover the mutation and open-world profile, so this is a strong supplement.

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

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

Four short sentences, front-loaded with the action and the batch limit, then failure behavior, then persistence and auth. Dense and free of filler, though the final 'Needs a token' is abrupt enough to read as an afterthought.

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 return behavior and does so for the failure path (answers come back with a reason). It does not describe what a successful response looks like, and slug goes unexplained, leaving a small residual gap for a 4-parameter write 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 only 50%, but the description compensates well for the key fields: it explains that row and basis originate from next_ai_cells, and that model records which model produced the value. The one gap is `slug`, which is not explained in either the description or 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 — 'Save up to 200 answers to an AI column' — and identifies the upstream source (next_ai_cells) that produces the payload. It is clearly distinct from the sibling fill_cells, which would fill ordinary cells rather than AI-generated answers.

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 establishes the workflow ordering implicitly by requiring each answer to carry 'the row and basis next_ai_cells gave it', so the agent knows to call next_ai_cells first. It also states the failure conditions (answer outside the column's choices, prompt changed since). It stops short of an explicit 'use this instead of X' exclusion, so it's a 4 rather than a 5.

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

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

Adds a lot beyond the annotations: quoted values are never replaced, proof-table writes only land in a draft, each cited page is opened before saving (so batches are capped at 25), and a token is required. It also discloses the response shape ('counts what saved and lists only the cells that didn't, with a reason') and the `unchecked` failure mode, which annotations alone (destructiveHint=false, idempotentHint=false) could 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?

Front-loaded with the action, the 200-cell cap, and the default origin rule before the mode-specific branches. It is dense and slightly tangled as it hops between the proof-optional and proof-required modes, but every sentence carries an actionable constraint, so 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?

For a two-parameter but structurally rich nested-cell payload with no output schema, the description covers value formats, provenance modes, batch caps, draft restriction, auth, and the return summary. The main remaining hole is how `row` is addressed (id vs label) and how partial failures interact with retries, given idempotentHint=false.

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

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

Schema coverage is only 50%, and the description compensates well: it defines the `origin` enum members and the defaulting rule (`link` with a source, otherwise `generated`), the date format YYYY-MM-DD, single-choice column constraint, the `quote` word-for-word requirement, and the `checked`/`none_stated` distinction. It leaves `row` and `column` addressing unexplained (the schema only says column id from get_table), so the gap is narrowed rather than closed.

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

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

Opens with a specific verb and resource plus a hard scope limit ('Set up to 200 cells of a table you run'), which tells the agent exactly what the call writes and how much. It implicitly contrasts with fill_ai_cells by describing human-supplied values, but never names that sibling, so the agent must infer the split between manual and AI cell filling.

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 detailed conditional routing: use `origin` in tables where proof is optional, use `value`/`source`/`quote` where proof is required, use `checked` when no acceptable source states it, and `none_stated` only after reading the whole source. That is strong when-to-use guidance, but no sibling is named (e.g. fill_ai_cells vs this tool), so the top-level choice between tools is left implicit.

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 beyond the annotations by disclosing the auth requirement, that the copy lands as a private draft in your account, and that provenance/proofs are preserved in the copy — meaningful context for a write tool with openWorldHint and non-idempotent semantics. It does not warn that repeated forks create duplicate copies, which the idempotentHint=false implies but leaves unstated.

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, front-loaded with the action and result, followed by eligibility and the auth note. Every clause carries information; nothing is restated 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?

For a three-param, fully-described schema with annotations covering safety and mutability, this is nearly sufficient. The one gap is return behavior: with no output schema, the agent isn't told whether the new table's slug comes back, which matters for chaining into add_columns or fill_cells.

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 slug/owner/title are already fully documented with formats and defaults. The description adds nothing parameter-specific beyond the token prerequisite, which is not a schema field. 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 (copy/fork) and resource (table), the exact result (a private draft in your own account), and the motive (to extend or relabel). It also delineates eligible sources — any published public table or one you run — which separates it from create_table and get_table 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 condition for use (extend or relabel) plus a source-eligibility rule and a prerequisite ("Needs a token"). It stops short of naming alternatives such as create_table for from-scratch work or save_version for snapshotting, so the routing is clear but not exhaustive.

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, closed-world, non-destructive, so the safety profile is covered. The description still adds real behavioral substance: what `absent` means (source was read and yields no such value), what `confirmed` implies about second-reader backing, and how `conflicts`, `history`, and `watch` behave — context 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?

Purpose is front-loaded in the first clause, then each subsequent sentence documents one return field with no filler. The run-on density and backtick-heavy field listing make it slightly hard to scan, 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?

With no output schema, the description usefully explains the shape of the returned evidence (source, quote, url, confirmed, conflicts, history, watch), and the input side is fully covered by the schema. What is missing is the relationship to sibling read tools and any pagination or error 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?

All three parameters (slug, row, column) carry 100% schema descriptions pointing at list_tables/get_table for their values, so the schema does the heavy lifting. The description adds no interpretation of slug, row, or column, 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 makes clear this returns the evidence/provenance for a single cell value (source, quote, source type, read time), which is a specific resource. It never names a verb like 'get' or 'fetch' and never contrasts itself with get_table or check_claim, so an agent gets the what but not the boundary.

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: the mention of missing values, `absent`, `conflicts`, and `history` hints this is the tool for verifying or auditing a single cell. There is no explicit 'use this when…' and no routing away from siblings such as get_table (whole-table read) or check_claim (claim verification).

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, so the bar is lower, and the description adds return-shape semantics the annotations cannot: null means blank, `origins` records provenance of unquoted values, `ai` reports AI-column progress, `versions` lists saved versions. It does not mention payload size or cost limits beyond the paging advice.

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

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

Four short sentences, front-loaded with purpose followed by return contents and then operational advice; nothing is padded. The middle sentence is dense with field names but each earns its place as return documentation.

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 full burden of explaining returns, and it does so field-by-field (scope, columns/rules, summaries, rows, origins, ai, versions). Combined with fully documented params and read-only annotations, an agent can invoke this correctly without further information.

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

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

Schema coverage is 100%, so baseline is 3; the description still earns a bump by tying offset/limit together into a paging strategy and pointing at `versions` as the source of the `version` value. It adds no syntax or format detail beyond that.

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?

"Read a table" states a specific verb and resource, and the sentence enumerates exactly what comes back (scope, columns with rules, summaries, rows), so the agent knows what it gets. It never names a sibling (list_tables, get_cell, export_table) to contrast against, so differentiation is left implicit.

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 closing sentence gives a real tactic for large tables (read summaries first, page with offset/limit), and the schema hints slug comes from list_tables. But there is no explicit when-not or routing to alternatives such as get_cell for a single value or export_table for bulk extraction.

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 genuine value beyond them by describing the return shape, which matters because there is no 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?

Two short sentences, zero waste, with the purpose front-loaded and the result fields summarized compactly.

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-optional-param read tool with full annotation coverage, the definition covers purpose and result fields adequately. It leaves out any note on result limits or pagination when listing everything, which would matter for large libraries.

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

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

Schema description coverage is 100% and the single optional query parameter is fully documented in the schema, including the "leave out to list everything" behavior. The description adds nothing further about the 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?

"Find tables in the library" gives a clear verb+resource, and the second sentence enumerates the returned fields (slug, question, size, last read). It is distinct from get_table only by implication (plural results vs. one table); 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?

Usage is implied by "Find tables" and by the schema note that omitting the query lists everything, but the description never states when to use this versus get_table for a single table or how it relates to create_table/add_rows.

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 (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context: the 200-item batch cap, the blank-first/changed-second ordering, and the 'done' termination signal. It stops short of describing the shape of the returned prompt objects, which the missing output schema leaves to inference.

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?

Dense and front-loaded with the core purpose first, then workflow, then redo, then auth. The sentences are packed and slightly run-on, but every clause carries information the 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?

With no output schema and no annotations explaining return semantics, the description supplies the essential pieces an agent needs: batch size, ordering, the 'done' sentinel, and the round-trip pairing with fill_ai_cells. It leaves the concrete structure of each prompt entry (fields other than row/basis) 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?

With only 25% schema coverage, the description carries the burden well: it explains redo ('also re-answers generated values that came from outside the instruction'), the 200/limit batching, that slug identifies the table, and that column is optional by implication. It does not explicitly clarify the column-scoping parameter, keeping it just short of full compensation.

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 specific resource ('the next prompts to answer for a table's AI columns') and its batching behavior, making the read-batch nature unmistakable. Its pairing with fill_ai_cells effectively distinguishes it from the write sibling, though the leading phrase is a noun clause rather than a crisp verb+resource statement.

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 spells out the full workflow: fetch prompts, answer each yourself, send back via fill_ai_cells with row and basis, repeat until 'done'. The alternative (fill_ai_cells) is named with the exact condition that selects it, and the token requirement is flagged.

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

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

Annotations already declare destructiveHint=false and openWorldHint=true, and the description usefully confirms the human-approval gate ('nothing changes until the owner reviews') and discloses the Bearer-token auth requirement, which annotations cannot convey. It does not elaborate on what a rejected or duplicate proposal does, but the added context is substantive.

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, each carrying a distinct load: purpose, evidence rule, review workflow, auth. The core action is front-loaded and 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 7-parameter mutation with no output schema, the description covers the auth requirement, the non-immediate-effect guarantee, and the evidence constraint — the three things an agent most needs before calling. What a successful call returns (proposal id, status) and what happens to duplicate proposals are left unstated, which is 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 coverage is 100%, so the baseline is 3, but the description adds a real validation rule not present in the schema: the quote must be word-for-word from the source AND must itself state the value being proposed. That couples the quote and value parameters in a way an agent would otherwise miss.

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 ('Suggest a new value for a cell') plus the distinguishing mechanic (a proof quote, owner review before any change). An agent can tell this is a proposal workflow rather than a direct write like fill_cells, 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?

'The owner reviews it before anything changes' implies the propose-then-approve flow versus a direct edit, so the context is inferable. But it never names fill_cells or any other sibling as the alternative, nor states when not to propose (e.g., already-correct cells).

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 safety (readOnlyHint=false, destructiveHint=false), but the description adds context they don't: the snapshot is permanent and the link never changes, and the tool 'Needs a token' (auth prerequisite). That is real behavioral value beyond the structured fields. It doesn't explain what happens on repeated calls or what is returned, so not 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, both earning their place: the core action and permanence first, then the when-to-use guidance. No filler or redundancy.

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

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

For a 2-parameter tool with no output schema, the description conveys enough: what it creates (numbered version), that it's permanent, when to call it, and that a token is required. The one gap is that it never explains the slug parameter, which an agent must supply and whose format is undocumented.

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

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

Schema coverage is 50%: the 'note' parameter is documented in the schema, while 'slug' is not. The description implies the target is 'a table you run' but never says slug is the table identifier, nor does it clarify the note/version-label relationship. At 50% coverage the description should compensate more than it does, so baseline 3.

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

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

States a specific verb and resource: it freezes a table into a numbered, immutable version with a permanent link. An agent can distinguish this from fork_table or export_table because the description emphasizes a frozen snapshot as-it-stands-now rather than a live copy or export. It stops just short of naming a sibling outright, keeping it at 4 rather than 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 concrete triggering conditions: 'Do this before training on a dataset or citing a table.' That tells the agent exactly when the tool is appropriate. It does not say when not to use it or name an alternative tool, so it falls short of a 5.

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

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

The annotations already declare this is a non-read-only, non-destructive mutation, and the description adds useful behavioral context: AI values never overwrite what a person typed, linked, or quoted, and a token is required. The ambiguous phrase “needs proof to be optional” weakens the disclosure, but the key safety behavior is present and consistent with the annotations.

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

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

The description is front-loaded with the core action and instruction format, with no wasted exposition. The final sentence about proof and a token is somewhat opaque and slightly disrupts an otherwise clear structure.

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 annotations and no output schema, the description covers the central instruction-setting behavior and human-data preservation. It omits important details such as whether changing the instruction recalculates existing cells, how choices interact with instructions, and what role slug plays.

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

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

The description adds valuable meaning for the instruction parameter, including the brace syntax and an example like “Classify {Pitch} by genre.” However, it does not explain slug at all, and choices is left entirely to the schema despite only 50% schema description coverage.

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

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

The description clearly states the specific action: configuring a column as an AI column, changing its instruction, or reverting it to a plain column. It is easy to distinguish from fill_ai_cells because it sets the instruction that governs future AI work rather than filling cells, though it does not explicitly name that 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?

The description implies when to use the tool by describing the three modes of setting an instruction, but it never explicitly routes the agent away from alternatives such as fill_ai_cells or next_ai_cells. The phrase about needing a token is present, but the usage conditions remain only partially stated.

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