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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write, so the description is not carrying the safety burden alone. It still adds real behavioral context: duplicate handling on the index column with a `skipped_duplicates` result, that inserted rows are returned, the 100-row cap, and that the call is free. Missing only permission/auth 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?

Very short and front-loaded: the limit and row shape come first, then duplicate behavior, return value, and next step. The telegraphic fragments ('Then `enrich` with `dataset_id`', bare 'free') are efficient but slightly under-explained, keeping 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 two-parameter mutation tool with no output schema, it covers the key facts an agent needs: cap, row format, duplicate semantics, what is returned, cost, and the natural next call. Auth requirements and failure modes are the notable 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 coverage is 100%, so the baseline would be 3. The description goes beyond it by introducing the index-column duplicate concept, which is not expressed in the schema and explains how row contents are interpreted, plus restating the 100-item cap in operational 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 verb and resource ('Append up to 100 rows') with the row shape defined as objects keyed by input column name. It differentiates from the sibling `import_dataset_rows` for larger volumes, though the first sentence does not explicitly tie the operation to a dataset (that only emerges from the `dataset_id`/`id` reference).

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

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

Gives an explicit alternative for the over-100 case ('More rows: `import_dataset_rows`') and sketches the follow-on workflow ('Then `enrich` with `dataset_id`'). It does not say when to prefer this over `update_dataset_row` for modifying existing rows, so routing against that sibling 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 declare mutation, open-world, non-idempotent, non-destructive; the description adds the parts annotations cannot: it is asynchronous, credits are charged, `max_credits` causes a 422 with nothing charged, `estimate_cost` prices without running, and a webhook can receive results. It also says exactly where the output lands (`dataset_id` → `list_dataset_rows`).

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

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

Front-loaded with the one-line purpose, then example, then workflow — easy to scan. There is mild redundancy: 'Run a configured list build' and the Workflow's 'Starts an async run of a configured list build' restate the same fact, and the inline markdown links duplicate the sibling names used in Workflow.

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 fully by naming the return value (the list-build run), how to poll it, where rows materialize, and the follow-up enrichment call. For a 6-parameter async mutation this is complete enough to invoke correctly on the first try.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: `parameters` are values for the template's `{{ placeholder }}` keys, illustrated with a concrete JSON example. `tier` and `dataset_webhook_url` are left to the schema, so it stops short of a 5.

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

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

States a specific verb and resource ('Run a configured list build') and explains the distinguishing mechanism: the spec, prompt template, row cap, and credit cost live on a reusable template (id `cds_...`) so the caller only supplies `parameters`. That functionally separates it from `build_dataset`, though it never names that 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?

The Workflow block gives an explicit when-and-then sequence with named siblings: start the run, poll `get_run`, read rows via `list_dataset_rows`, then `enrich`. It does not state when *not* to use it (e.g. to define an ad-hoc spec, use `build_dataset`), so the alternative routing is implied 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 declare non-readonly, open-world, non-destructive, but say nothing about cost. The description carries that burden well: `rows` is free, prompt+count is paid, budget is charged at kickoff and settled, `auto_fill` triggers a second paid run, and `max_credits` causes a 422 credit_cap_exceeded with nothing charged. That is exactly the behavioral context annotations cannot express.

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 but front-loaded: the mode split and the return shape come before the examples, and the three examples each demonstrate a distinct parameter combination rather than repeating prose. The opening line "build dataset" only echoes the name and title and is wasted space in an otherwise efficient definition.

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

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

For a 13-parameter tool with no output schema, the description covers the return value (`id`, `ds_...`, and `run` or null), the follow-up calls, and the cost model. An agent has enough to choose a mode, construct a valid request, and know what to do with the response.

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 100% schema coverage the baseline is 3, but the description adds relational meaning the schema does not: the rows/propmt-count mode split, the attributes-vs-enrichment_id exclusivity in practice, and the fact that output columns are written from the prompt when neither is supplied. It also restates budget's default formula, which is already in the schema, so it stops short of a 5.

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

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

States a specific verb and resource ("Build a dataset") and immediately splits the tool into its two functional modes: rows you send vs rows Riveter finds. That framing distinguishes it from add_dataset_rows, import_dataset_rows, and build_configured_dataset without opening any schema.

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

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

Gives concrete when-to guidance: use `rows` for data you have, `prompt` + `count` for generation, `estimate_cost: true` to price first, and `help` with `datasets` for more. It also states the post-build workflow (poll `get_run`, read with `list_dataset_rows`). It never explicitly says when to prefer sibling tools like build_dataset_rows or build_configured_dataset, which keeps this below 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?

Goes well beyond the annotations: discloses billing and settlement behavior, that the generator skips existing rows and may return fewer than requested, the exact progress counters (requested_rows, generated_rows, added_rows, skipped_duplicate_rows), and auto_fill semantics. The return shape (dataset and run) is also stated, which 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 key requirements and cost warning are front-loaded, and the worked JSON example is genuinely illustrative rather than filler. Minor waste from echoing the title phrase ('generate more rows') before the real sentence.

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

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

For a 9-parameter, non-idempotent, open-world mutation with no output schema, the description covers cost, prerequisites, side effects, and return shape. It leaves the budget vs max_credits distinction entirely to the schema, which is a small residual 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% and the schema already documents every parameter including defaults and the max_credits 422 behavior. The description adds the useful default-source detail for `prompt` (the dataset's last build prompt) and the effect of auto_fill, but largely restates what the structured fields provide, 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 ('Generate `count` more rows for a dataset'), making clear this extends an existing dataset rather than creating one. It does not explicitly name the nearest siblings (build_dataset for initial builds, add_dataset_rows for manual rows), so the differentiation is implied rather than stated.

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

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

Gives real preconditions: paid operation, call estimate_cost first, dataset needs an index_column set via update_dataset. That is clear context for when to use it, though it stops short of explicit alternatives and when-not conditions relative to add_dataset_rows or build_dataset.

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

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

Annotations only say not-readOnly, not-destructive, not-idempotent; the description adds meaningful behavior: no run is triggered, no credits are spent, an empty dataset is created and bound, a 422 is returned when `dataset_id` alone has no output columns, and budget auto-adjusts by 1.5 credits per column unless `budget_locked`. It doesn't cover permissions or what the response looks like beyond the id/name/app_url tuple, keeping it below 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 opening line and the 'Prefer prompt alone' directive are front-loaded, and the three examples are labeled and useful. The first paragraph is a dense run-on packing ~8 distinct rules into one block, which costs some readability.

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 both call modes, the sequencing with `add_dataset_rows`/`enrich`, the error path, budget semantics, and the tool-pinning feature, backed by three concrete payload examples. For a 9-parameter tool with no output schema, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description still adds cross-parameter meaning — the string shorthand for `output`, `tool: "<list_tools name>"` semantics ('one call per row, result is the cell'), budget default and its movement on column add/remove, and the `only_tools` vs `additional_tools` relationship. This goes beyond the per-property 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 and resource plus its scope: creating an enrichment that does NOT run and is free, along with the empty dataset it fills. It also distinguishes the two modes (recipe creation vs. `dataset_id`-only lookup of a dataset's own enrichment), so an agent can tell it apart from `enrich`, which actually runs.

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 routing: create here, then `add_dataset_rows` on the returned `dataset_id` and `enrich` with it (marked preferred), versus `enrich` with `enrichment_id` + `input` for a one-off. It also says 'Prefer `prompt` alone' and names `update_dataset` for the 422 case with no output columns.

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 carries real behavioral weight beyond the annotations: discovery is async and returns no run (a common failure mode for an agent expecting a run handle), credits are charged and surfaced as `credits_charged`, and the estimate path charges nothing. It does not note that the call is non-idempotent (idempotentHint=false), so a retried request would silently create a second extraction — a meaningful omission for a create tool with no annotations covering duplication.

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 verb and the resource definition, then workflow, then example — a sensible ordering that lets an agent stop reading once it has what it needs. It loses a little to the redundant lowercase "create extraction" opener that merely restates the title and to the URL-fragment link syntax, which is noise in an agent-facing description.

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?

This is a 7-parameter, multi-step, credit-charging async operation with no output schema, so the description must do the work — and it largely does, covering the async contract, the charge, and the follow-up call. It is a bit thin on what the create response actually contains beyond `credits_charged` and `status` (field names an agent would poll on are only implied).

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 seven parameters (including the 422 credit_cap_exceeded behavior for max_credits); baseline is 3. The description goes past that by supplying a worked example that shows the relationship between starting_url, goal_description, output_record_json_schema and required_keys, and by restating estimate_cost as an actionable pricing switch.

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

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

States a specific verb and resource ("Create an extraction — a reusable recipe for scraping structured records from a website") and immediately bounds the scope: it creates the recipe, not the runs. It explicitly distinguishes the extraction (`ext_...`) from its runs (`run_...`) and names the siblings that operate on each, so an agent can separate it from run_extraction/get_extraction 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 the full lifecycle: create → poll `get_extraction` until status is `ready` → execute with `run_extraction`, plus the escape hatch of `estimate_cost: true` to price before committing. When-to-use, what to do next, and which sibling handles each step are all explicit; nothing is left to inference.

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

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

Beyond the annotations, the description discloses the billing model (creation free, every run charged, estimate_cost prices one run), the comparison behavior between runs, the webhook firing modes, and the fact that dataset monitors use the dataset's rows rather than input. This is substantial behavioral context for a mutating, non-idempotent tool.

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

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

The description is front-loaded with the core definition and then uses examples and a workflow sentence, which is appropriate for a 16-parameter creation tool. It is slightly long and opens with a redundant lowercase 'create monitor', but the examples and structure earn their 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?

Given the high parameter count, nested input object, and absence of an output schema, the description is complete enough to call the tool correctly. It covers the schedule, cost model, webhook behavior, dataset versus legacy enrichment distinction, examples, and follow-up workflow while relying on the schema for exhaustive parameter details.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds practical meaning through examples and clarifications such as omitting columns meaning all output columns, dataset monitors not using input, and estimate_cost returning a price without running. It does not add prose semantics for every parameter, but it improves the most important ones.

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

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

The description states a specific verb and resource, then explains the monitor's distinctive behavior: scheduled re-filling of dataset output columns, cell-by-cell comparison with the previous run, and optional webhook posting. It also names the sibling tools used to inspect, pause, and list runs, making it clearly distinguishable from create_enrichment or update_monitor.

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 post-creation workflow guidance with get_monitor, update_monitor, and list_monitor_runs, and explains that dataset_id is the normal path while input is for legacy enrichment monitors. However, it does not explicitly state when to choose create_monitor over other creation tools or when not to use it.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds meaningful behavior not in structured data: rows and cells are removed, enrichments survive, and a specific 409 `dataset_in_use` condition fires while a run is active. That cascade and error semantics materially reduce the risk of a mistaken destructive call.

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 body is two tight, front-loaded sentences with the cascade semantics and the error condition in priority order. The leading 'delete dataset' line merely restates the name/title and could be dropped, a minor 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?

With no output schema and a trivial one-param input, the description covers what an agent needs: what gets destroyed, what survives, and the blocking condition. It does not state the success response shape or whether the deletion is immediate vs. queued, but that is a small gap for a destructive delete.

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 single `id` parameter is fully documented in the schema (including the `ds_...` format), so the description's 'by id' phrasing adds nothing beyond it. Baseline 3 is appropriate when schema coverage is 100% and the description supplies no extra format or lookup guidance.

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 ('Delete a dataset by id') and clarifies the cascade scope (rows and cells go with it; enrichment stays). It does not explicitly contrast with the sibling delete_dataset_rows, so the agent must infer the distinction, but the scope of this tool is 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?

States a concrete precondition: a 409 `dataset_in_use` error occurs while a run is on the dataset, which tells the agent it must ensure no run is active first. It stops short of naming an alternative tool for deleting individual rows or handling the 409 course of action.

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 adds genuine extra context: a 100-row cap per call and the fact that it returns the number deleted. It does not dig into partial-failure behavior or what happens with invalid ids, keeping it at a solid but not rich 3.

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 with the operational rule and the return value front-loaded; nothing wasted beyond the lowercase 'delete rows' fragment that merely echoes the title.

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

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

For a destructive 3-parameter tool with full schema coverage and annotations carrying the safety profile, the description covers the batch cap and return shape, leaving little an agent needs to know. Edge cases (nonexistent ids, partial deletes) are omitted but are minor at 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 explains ds_/row_ prefixes, comma-separated syntax, 1-based positions, and the 100-row combined limit. The description restates the same combination rule without adding format nuance, which is baseline 3.

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

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

The description states a specific verb and resource ('Remove rows' from a dataset) and enumerates the two ways to identify rows, which distinguishes it from siblings like delete_dataset, update_dataset_row, or list_dataset_rows. It does not explicitly name a sibling it might be confused with, so 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?

Usage is implied by the 'ids and/or positions' framing and the note that one is required, but there is no explicit when-to-use versus when-not-to-use guidance or reference to alternatives. An agent can infer the purpose from the model, but routing is left to the reader.

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, so the safety profile is covered. The description adds value the annotations cannot: a dataset bound to the enrichment keeps its columns, and legacy ids fail with a specific 422 error code. The phrase 'runs in flight finish' is opaque and the re-delete/idempotency behavior is not spelled out beyond the hint.

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, three short sentences with no filler. The only waste is the leading lowercase restatement of the tool name, which duplicates the title and the first clause.

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 one-parameter destructive tool with rich annotations and no output schema, everything an agent needs is present: what is deleted, what collateral state is preserved (dataset columns), and the specific failure mode for legacy enrichments.

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?

There is a single required parameter with 100% schema coverage, so the baseline is 3. The description goes one step further by explaining the id namespace constraint (legacy ids are rejected with 422), which is meaningfully more than the schema's 'enr_...' format 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?

The description states a specific verb and resource ('Delete an enrichment by id'), which is unambiguous and separable from siblings like get_enrichment, update_enrichment, and delete_dataset. An agent can identify the operation without consulting 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 gives a clear negative condition: legacy enrichments are refused with a 422 `legacy` and must be deleted in the app instead. That is real routing guidance. It does not, however, contrast with delete_dataset or discuss any prerequisite checks (e.g., confirm the id first with get_enrichment).

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 the write/open-world/non-destructive profile, and the description adds important runtime behavior: async runs, polling with `get_run_result`, `estimate_cost`, webhooks, `run_key` duplicate 409s, credit-cap 422s, and legacy-mode responses. These are meaningful operational details beyond the annotation surface.

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 and well organized around row source, config source, examples, and workflow. It is long, but the 17-parameter surface and nested config justify most of the length; some examples and schema-adjacent restatements could be trimmed.

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, but the description fills that gap by explaining that the tool starts an async run, how to poll it, what dataset-fill results look like, and how to use `estimate_cost`. For a complex mutation tool with nested parameters and no output schema, this is complete enough 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?

Although schema coverage is already 100%, the description adds relational semantics that the schema alone only partly conveys: rows come from exactly one of `dataset_id` or `input`, column config is exactly one of the three ordered modes, and conditional row limits differ by mode. It also explains preferred workflow, default scope, and how `force`, `states`, `columns`, `rows`, and `positions` interact.

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 immediately states the specific action: adding AI-researched columns to rows. It clearly distinguishes the two row sources (`dataset_id` vs. inline `input`) and explicitly routes dataset-preparation work to the sibling `build_dataset`. An agent can identify the tool's role 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 explicitly gives a preferred workflow, names alternatives like `build_dataset` and `update_dataset`, and explains when each configuration mode applies. It also states exclusions such as `output` being refused with `dataset_id` and clarifies default scope versus narrowed scope.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the output is 'CSV text' with input columns then output columns, one line per row, and that xlsx is binary and browser-oriented — a critical operational caveat for an agent that can't handle binary. It does not discuss size limits or truncation.

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

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

The first line restates the title verbatim, which is dead weight, and the second sentence stacks parentheticals (jsonl note, xlsx note, list_dataset_rows note) that tax readability. The useful content is front-loaded, but it could be tightened to two clean 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 usefully describes the returned shape (CSV text, input then output columns, one row per line) and the format alternatives. Combined with annotations covering safety, an agent has enough to call it correctly; the only gap is behavior for large datasets or pagination.

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 both parameters are already documented with an enum. The description still adds meaning beyond the schema by explaining what `jsonl` produces and flagging that `xlsx` is binary/browser-suited, which affects how an agent should pick a format.

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 (export dataset) and enumerates the supported formats (CSV, Excel, JSON Lines), making the operation unambiguous. It also names a sibling (list_dataset_rows) for the small-row case, though the opening line mostly repeats the title rather than framing the 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 gives an explicit alternative with a condition: 'For a few rows prefer `list_dataset_rows` (it carries cell states).' It also implicitly steers away from xlsx for agent use by noting it is binary and meant for a browser. No guidance on very large exports or rate/size limits, but the core when-to-use routing 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 already cover the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real context beyond them: it discloses that the response uses the legacy `request_status` format and that the data is scoped to the API key's account, both of which affect how an agent should parse the result.

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

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

Two tight sentences with the payload contents front-loaded, plus a useful legacy-format caveat. The leading bare word "account" on its own line merely restates the name and earns nothing, which keeps it out of the top band.

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 must carry the return-value burden; it identifies the main response contents and flags the legacy format. It stops short of describing the actual field layout of the `request_status` envelope, but for a 0-param read-only lookup this is nearly 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. Nothing is missing in this dimension.

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 and its contents specifically: plan, credit balance, and API-key metadata for the account tied to the credential. No sibling tool touches account data, so it is trivially distinguishable, though the verb is implied ("Information about...") 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?

Usage is only implied — an agent can infer this is the tool to call when it needs credit/plan status, and no sibling competes for that role. There is no explicit when-to-use or exclusion statement, so it stays at the implied-usage level.

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 substantive behavioral content on top: the payload includes `import_in_progress`, signalling that a dataset may be mid-import and its data incomplete, and that `runs` is only the newest set rather than history. It does not mention permissions or failure behavior for a bad id.

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?

Very compact and front-loaded: identification first, payload contents second, sibling routing last. Every clause carries information and none is filler. The telegraphic, punctuation-dense formatting is slightly harder to parse than plain sentences, which keeps it off 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?

With no output schema, the description takes on the job of describing returns and does so field by field, including the subtle import-state flag. Combined with the annotation coverage, an agent has what it needs to select and invoke this correctly. It omits what happens on a missing or malformed id, a small 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?

There is a single parameter at 100% schema description coverage, with the `ds_...` format documented in the schema itself. The description says "by id" but adds no format, validation, or lookup-failure semantics beyond that. Baseline 3 is correct when the schema fully carries the parameter.

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

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

States a specific verb and resource ("read dataset", "One dataset by id") and immediately enumerates the returned fields, which lets an agent recognize this as the single-resource fetch. It distinguishes itself from list_datasets and list_dataset_rows by explicitly noting rows come from the other tool. Only minor deduction for the bare heading, which is tautological on its own before the body clarifies.

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 routing for two adjacent needs: row data goes to `list_dataset_rows`, and enrichment prompt text goes to `get_enrichment`. That is real when-to-use-something-else guidance rather than implied usage. There is no explicit statement of preconditions or when not to call it at all, 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 already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description goes beyond that by disclosing the shape of what comes back — prompt, input_columns, output column fields, tools, budget_credits_per_row, version — and by explaining the `legacy`/`successor` key, which is real behavioral context not present in any structured field.

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 verb and scope, then a compact field enumeration. The second sentence is dense but every listed field earns its place because there is no output schema to carry the return shape.

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 takes on the burden of describing return fields and does so, plus it explains the legacy-id/successor edge case that an agent would otherwise misread. Nothing essential to calling this one-parameter read 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?

There is a single parameter with 100% schema coverage ('The enrichment id (enr_...)'), so the schema already carries the semantics. The description reinforces that the id identifies exactly one enrichment but adds no format or edge-case detail beyond that; baseline 3 is appropriate.

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

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

States a specific verb+resource ('read enrichment') and narrows scope to 'One enrichment by id', which implicitly distinguishes it from the sibling list_enrichments. It never names the sibling outright, but the singular-by-id framing is enough for an agent to tell them apart.

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: use this to fetch a single enrichment when you already have an id. There is no explicit guidance on when to prefer it over list_enrichments, get_extraction, or get_run, and no prerequisites or failure conditions are mentioned.

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 non-destructive, so safety is covered. The description adds genuinely new behavioral content beyond them: the state machine of status values (discovering / ready / discovery_failed) and the condition under which execution becomes valid. It does not describe what the 'definition' payload contains.

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 payload statement comes first and the lifecycle/next-step guidance second, with no wasted clauses. The redundant 'get extraction' lead line is the only dead weight.

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 the response, and it only sketches it as 'status and definition' without indicating what the definition object holds or how failure details appear. The lifecycle coverage is good; the return-value coverage is thin for a tool whose whole job is retrieving that payload.

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?

Only one parameter, and the schema fully documents it as 'The extraction id (ext_...)' with 100% coverage. The description adds no format, prefix, or lookup guidance beyond what the schema already gives, so it sits at the baseline for high schema 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 body states precisely what is returned: the extraction's status and definition, for a specific extraction id. The heading 'get extraction' merely restates the name/title and adds nothing, but the second sentence makes the resource and payload unambiguous, so an agent can distinguish it from create_extraction or run_extraction.

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 status lifecycle ('discovering' while the agent builds the plan, then 'ready') tells the agent this is the polling tool, and the closing sentence routes it to POST /extractions/{id}/runs once ready. It stops short of an explicit 'call this repeatedly while discovering' instruction or naming the sibling run_extraction by 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 establish readOnly, idempotent, non-destructive and closed-world behavior, so safety is covered. The description adds genuinely new behavioral information not in structured fields: the set of fields returned and the special 'legacy' response for monitors on legacy enrichments.

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 return payload. The leading 'get monitor' line duplicates the title and earns little, but the rest is dense with no padding.

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 one-parameter read tool with no output schema, the description covers the return shape at a useful level and flags the legacy edge case. It stops short of describing the nested schedule/webhook structure an agent might need to parse, but it is sufficient to call correctly.

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

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

There is a single required parameter and schema coverage is 100%, with the schema itself documenting the 'mon_...' id format. The description adds nothing about the 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 the resource (monitor) and enumerates what it returns — schedule, webhook, next run time, dataset and columns — which is more than a restatement of the title. It does not explicitly distinguish itself from list_monitors or get_enrichment, but 'get' plus the required id makes single-resource retrieval clear.

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

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

Usage is only implied: fetch one monitor's detail by id. There is no statement of when to prefer this over list_monitors or how it relates to list_monitor_runs, and no prerequisites or 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 already cover the safety profile (read-only, idempotent, non-destructive), while the description adds important operational behavior: wait triggers long-polling that holds the request, and polling should continue until a terminal status. It does not discuss auth requirements, rate limits, or failure statuses, but the key non-obvious behavior is disclosed.

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 short, front-loads the core purpose, and highlights the polling workflow. It repeats the max-50 wait constraint and long-poll concept across the wait paragraph and workflow paragraph, but the repetition is minor and does not obscure the guidance.

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

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

For a simple status-check tool with no output schema, the description explains the return concepts (status and progress) and the polling behavior sufficiently. It omits some possible terminal states such as failure, but overall an agent has enough information to call and poll 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, but the description adds meaningful context for wait: it long-polls, holds until the run finishes or the budget elapses, and should be repeated until a terminal status. This goes beyond the schema's 'Seconds to long-poll' wording, though the id parameter adds no 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?

The description clearly states that this tool returns the status and progress of a run, and it scopes that to runs created from enrichments, datasets, or extractions. It distinguishes status/progress from result retrieval implicitly, but it does not name the sibling get_run_result or otherwise explicitly route the agent away from alternatives.

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

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

The description gives a concrete polling workflow: pass wait, hold until completion or timeout, and repeat until status is 'success' or 'stopped'. It does not explicitly compare this tool with get_run_result, list_runs, runs_summary, or stop_run, so alternative selection remains somewhat 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description adds value on top: the null-until-finished contract, the long-poll hold semantics, the 5,000-row threshold where `output` flips to `null`, 30-day row expiry, and `output_files` being signed links valid one hour with a `pending` state. These are exactly the non-obvious behaviors an agent needs and none of them are 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?

The header structure (Output shape by run type, Workflow) makes a long description scannable, and the length is justified by the absence of an output schema. It loses a point for the wasted 'run result' opener and for repeating the '>5,000 rows or 30-day expiry → `output` is null' rule three times in near-identical wording.

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 full return-shape burden and does so per run type, including the legacy `/web_search` caveat and the dataset-enrichment row shape. The remaining gap is that the run object's own fields (status, error) are never described, so an agent must discover elsewhere how to tell a finished run from a failed one.

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 goes beyond the schema by explaining what `wait` actually does — the request holds until the run finishes or the budget elapses, whichever comes first — rather than just stating a 0–50 range. `id` gets no added meaning beyond the schema's 'run_...' hint.

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 body states concretely what is returned: the run object plus `output`, which is `null` until the run finishes, and it enumerates the payload shape per run type. That is far more specific than the tautological opening line 'run result', which merely restates the title. It never distinguishes itself from the sibling `get_run`, leaving the agent to infer the split.

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 real usage guidance for polling: 'Pass `wait` (seconds, max 50) to long-poll instead of sleeping between calls' and a Workflow note repeating that `output` is null until the run finishes. However, no alternative is named — the sibling `get_run` exists and the description never says when to call that instead, nor what to do on expiry or error.

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 fully covered. The description adds only that this returns static reference text keyed by topic, and does not mention response format (markdown vs plain text) or size. Useful but modest value beyond structured data.

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-load purpose and the primary trigger, then list topics. The topic enumeration duplicates the enum verbatim and costs space, but it aids scanning and is not harmful.

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?

Single required parameter, no output schema, fully described enum; the description supplies the situational triggers the schema cannot. It could close the loop by stating what the docs return, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and the `topic` enum lists all 16 values with a description ('Which topic to read'). The description re-lists the same topics and adds no semantics about how to choose between overlapping topics (e.g., datasets vs datasets_vs_enrichment). Baseline 3 is appropriate when the schema does the work.

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 ('Reference docs') scoped to the Riveter product and enumerates the available topics, which makes it unmistakable against siblings like list_tools or get_account. 'Using Riveter well' is slightly marketing-ish phrasing, but the topic list grounds the purpose concretely.

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 call triggers: before authoring an `output` column spec, and when an error mentions a limit. That is real when-to-use guidance rather than implied context. It doesn't say when the tool is unnecessary (e.g., for run status, use get_run), 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?

Annotations already mark this as a non-read-only, non-destructive, non-idempotent mutation. The description adds important behavior beyond that: rows are appended, output values land as manual cells, up to 1,000 rows complete synchronously, larger imports run in the background, and duplicate index values are skipped. These are exactly the operational details an agent needs.

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

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

The description is dense and front-loaded around the append/CSV behavior. It repeats the title at the start and is somewhat run-on with status jargon, but every sentence carries useful 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 two-parameter import tool with no output schema, the description covers the key async threshold, status values, duplicate handling, and cell landing behavior. It lacks error handling and permission details, but it is otherwise complete enough to invoke correctly.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description adds real meaning about the csv parameter: the first row contains input and/or output column names, and output values become manual cells. It does not add much about the id parameter, but the CSV semantics go beyond the schema.

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

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

The description states a specific verb and resource: append rows from CSV text to a dataset. It clearly distinguishes this as a CSV import operation, but it does not explicitly contrast it with sibling tools like add_dataset_rows or build_dataset_rows.

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 CSV-specific wording and the append semantics, but the description never says when to prefer this tool over add_dataset_rows or build_dataset_rows. It also gives no prerequisites or 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 this as a safe, read-only, idempotent operation, so the description appropriately focuses on row structure and pagination behavior. It adds useful context about output fields such as `input`, `cells`, `state` values, `credits`, and `not_found_reason`, which is especially helpful because no output schema exists.

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

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

The description is front-loaded with the core purpose and then efficiently packs row shape, state values, pagination, and filtering into a short passage. The opening 'list rows' is somewhat redundant with the tool name/title, and the dense enumeration of output fields is useful but slightly run-on.

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 operation with rich annotations and a fully described input schema, the description is largely complete. It explains the returned row structure and pagination, which are not covered by an output schema, though it could clarify edge cases like empty results or terminal cursor 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 schema already documents `id`, `limit`, `cursor`, and `updated_since`. The description reinforces pagination by connecting `next_cursor` to `cursor` and clarifies `updated_since` as 'changes only', but adds only marginal 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?

The description states a specific verb and resource: listing rows of a dataset in position order. It is distinguishable from siblings like list_datasets or get_dataset by focusing on row-level data, though it does not explicitly name alternatives or contrast 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?

The description gives practical guidance on pagination (`limit` up to 1,000, `next_cursor` as `cursor`) and filtering via `updated_since` for changes only. However, it does not explicitly state when to use this tool versus alternatives such as get_dataset, export_dataset, or list_datasets.

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, and non-destructive, so safety is covered. The description adds value the annotations do not: a hard cap of 200 results, newest-first ordering, and the exact fields returned. It does not discuss pagination beyond the cap, which is the only gap.

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 scope then routing. The leading 'list datasets' restates the title and earns little, but the rest is dense with useful 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?

There is no output schema, so the description's field list (id, name, column counts, row_count, newest run) and the 200-item cap are the only place an agent learns what comes back. Nothing needed to call this zero-arg tool correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly spends no space on parameter semantics and instead documents the fixed output shape.

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?

Names a specific verb and resource (list datasets) and immediately scopes it: the account's datasets, newest first, capped at 200. It also distinguishes itself from get_dataset by noting that sibling carries the columns and enrichment, so an agent can choose without opening either 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 closing sentence routes detail-seeking calls to get_dataset, which is an explicit alternative. There is no explicit 'do not use for X' beyond that, but for a zero-parameter listing tool the usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: ordering ('newest first'), legacy-specific fields (`status`, `app_url`, `dataset_id`), and a pointer that dataset copies should use `enrich` instead. The parenthetical about dataset copies is somewhat vague, but overall it adds value beyond 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 opening 'list enrichments' is redundant with the title, and the parenthetical '(its dataset copy: `enrich` that instead)' is syntactically awkward and slightly cryptic. The content is informative but not as tightly front-loaded or waste-free as it could be.

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, but the description lists the key returned fields and notes legacy-specific additions, which is enough for an agent to understand what to expect. It also covers filtering, pagination, and an alternative for full column config. It does not describe the pagination response envelope (e.g., total count), but that 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 description coverage is 100%, so the baseline is 3, but the description adds a crucial semantic not present in the schema: `status` filtering is legacy only. It also restates max 50 for `per_page` and mentions filtering by `name`, which are already in the schema, so the addition is meaningful but not extensive.

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 ('list enrichments') and then specifies the returned fields ('id, name, input / output column names') and ordering ('newest first'). It also distinguishes the tool from `get_enrichment`, which provides column config, so an agent can tell the two apart without opening either 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 filtering and pagination guidance ('Paginate with page / per_page (max 50); filter by status (legacy only), name') and points to `get_enrichment` for detailed column configuration. However, it does not explicitly state when to prefer this tool over `list_datasets` or other listing tools, so it lacks full exclusion guidance.

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

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

The annotations already cover safety, idempotency, and closed-world behavior. The description adds useful behavioral context beyond them: run history is returned newest first, and legacy enrichment monitors return a `legacy` marker.

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 short and front-loads the core purpose. It wastes a little space by repeating the title as the opening line and includes a raw API endpoint link, but otherwise every part is useful.

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 with full schema coverage and clear annotations, the description covers ordering, filtering support, pagination parameters, and the legacy case. It could say more about pagination metadata or response shape, but is complete enough 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. The description mentions `status`, `page`, and `per_page`, but adds little semantic meaning beyond what the schema fields and enum already provide.

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: listing a monitor's run history, ordered newest first. It distinguishes this from fetching a specific run's data, though it points to a raw API endpoint rather than naming the sibling tool that performs that retrieval.

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

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

It implies this tool is for listing a monitor's run history and directs specific-run retrieval elsewhere. However, it does not explicitly name sibling alternatives such as get_run, get_run_result, list_runs, or runs_summary, nor does it state when not to use this tool.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds real value by disclosing result ordering ('newest first') and the meaning of the `legacy: true` field, which the agent cannot get from annotations or 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?

Very short and the meaningful content is front-loaded. The leading lowercase 'list monitors' line duplicates the name/title and is minor waste, but the rest of the text is efficient.

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 input params and no output schema, the description needs to convey return-value shape; it partially does so by mentioning ordering and the `legacy` field. Missing pagination or result-count behavior keeps it from a 5.

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 tool takes zero parameters, so there is nothing to document in the schema. Baseline of 4 applies; no parameter semantics are needed or 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?

States a specific verb and resource ('List the account's monitors') and adds scope plus ordering. It implicitly distinguishes itself from get_monitor and list_monitor_runs, though it doesn't name them 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: it lists all monitors in the account with no filtering. There's no explicit statement of when to prefer get_monitor or list_monitor_runs, so the agent must infer the alternative from sibling names.

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 readOnly/idempotent annotations with real behavior: newest-first ordering, the fact that filters and pagination are silently ignored in `ids` mode, `not_found` reporting for foreign ids, and a `legacy` marker on legacy-enrichment runs. Gaps remain on pagination defaults/limits and on how the list is bounded, which matter for a 10-parameter listing 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?

Front-loaded with purpose, then filters, then the special `ids` branch — a sensible ordering with no filler sentences. The leading lowercase 'list runs' line merely restates the tool name and could be cut.

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 all ten parameters, both operating modes, and the notable edge cases (legacy, not_found), which is strong for a tool with no output schema. The only shortfall is that the returned list object's shape is never characterized beyond the `ids` mode matching `GET /runs/{id}`, leaving the agent to infer what fields a run row carries.

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 nominally 100%, but several schema descriptions are placeholders ('page', 'per_page', 'created_after'), so the description earns credit by adding ISO 8601 formatting for the date bounds, comma-separated semantics for `type` and `ids`, the 100-id cap, and the rule that other filters are ignored in `ids` mode. It stops short of documenting page-size defaults or the meaning of negative minimums 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?

States a specific verb and resource ('List the account's runs, newest first') and enumerates what is included (enrichment runs, dataset builds, extractions, quick searches), which disambiguates it from narrow siblings like list_monitor_runs and get_run. It does not name those siblings explicitly, so differentiation is implied through scope 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?

Clear about the two operating modes: filtered/paginated listing versus an `ids` batch lookup whose semantics match `GET /runs/{id}`, which implicitly routes the agent away from calling get_run repeatedly. It does not explicitly say when to prefer runs_summary or get_run for aggregates or single-run reads, so one class of alternative is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description still adds real behavioral content beyond them: `price_note` semantics per tool (per-page, per-token, settled-after-call), the `api_key_linked` refusal rule ('refused until it is'), opt-in/enabled state, and the `budget` per-row range. It omits return shape/ordering and list size, 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?

Information density is high and nothing is truly filler, but it is delivered as one enormous run-on sentence stitched together with em-dashes and nested parentheticals. The lead line is just the title repeated, so the genuinely useful content is not front-loaded and an agent must parse the whole block to extract the schema of the response.

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 parameters, the description correctly takes on the job of describing the returned record in detail, including conditional pricing and key-linkage fields. It is nearly complete; only the container shape (array vs. object), ordering, and volume of the result are 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description's field-level vocabulary (`inputs`/`required`, `input_groups`, `returns`) concerns the response payload, not the call signature, and does not confuse the two.

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 restatement of the title, then specifies the resource precisely: the catalogue of agent tools usable in an enrichment's `only_tools`/`additional_tools` or pinned to an output column, with the fields each entry carries. That is a clear verb+resource. It never names a sibling (e.g. `help`, `get_account`) to draw a boundary, so it stops 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 implied rather than stated: the reference to `only_tools`/`additional_tools` and pinned output columns tells an agent the context in which this list matters, but there is no explicit 'call this before create_enrichment/update_enrichment' or 'do not use this to look up a specific tool by name'. No alternatives or 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 already declare destructiveHint=true and idempotentHint=false; the description adds genuinely new context: the operation is not undoable, values move with the column, and a 409 `dataset_in_use` is returned while a fill is running. That error-condition disclosure is valuable beyond the annotations, though the resulting state after conversion is only loosely described.

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 verb+resource leads, consequences follow, and failure mode is last — good front-loading. The opening line duplicates the title verbatim, which is a small redundancy but not costly.

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, non-idempotent two-parameter mutation with no output schema, the description covers reversibility, data movement, and the key error case. What's missing is any hint of the returned representation or whether the previous input columns are affected.

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 both `id` and `column` are already documented. The description reinforces that `column` must be the name of an existing filled output column and that the promoted column keeps the same name, which is modest added meaning over 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?

States a specific verb and resource ('convert output column to input') and names the exact object affected ('`column`'). No sibling tool does anything comparable, so an agent can identify it uniquely 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 rationale ('so later columns and dedupe can key on it') implies when this is useful, and the 409 condition signals when it will fail. But there is no explicit guidance on when to choose this over, e.g., rebuilding the dataset via build_dataset, nor any stated preconditions about the fill having completed.

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

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

Beyond annotations, the description discloses important behavior: it is synchronous, requires no polling or webhook, stores the result for later re-fetch, and costs 0.04 credits per search. It does not itself cover every failure or auth detail, but the schema documents max_credits and estimate_cost, and the annotations already declare open-world and non-read-only behavior.

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

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

The purpose and sync behavior are front-loaded well, but the description includes a redundant opening line and duplicative examples: the curl example is followed by two JSON examples that partly repeat the same request shapes. The content is useful, but some sentences and examples do not fully earn their 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?

Given six parameters, no output schema, and a web-search operation, the description covers the key calling context: synchronous result delivery, result persistence, date filtering, bulk alternative, and credit cost. It does not detail the exact result object shape, but it explains that structured results appear in output and remain re-fetchable.

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 explains query, run_key, date filters, max_credits, and estimate_cost. The description restates the date filter format and default for date_end, but does not add much parameter meaning beyond the already complete schema; baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: run a web search and return structured results synchronously. It also distinguishes this quick synchronous tool from the bulk asynchronous legacy endpoint, so the scope is clear without needing to open 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 clearly routes bulk workloads to the legacy POST /v1/web_search endpoint and describes the quick_search case as a single synchronous search. It does not explicitly compare against other siblings such as search_agent or scrape, but the intended usage context is strong.

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 openWorld/non-idempotent/non-destructive, the description adds real behavioral context: the call is async, returns a run rather than records, consumes run credits per invocation (`credits_charged`), and can be refused with 422 credit_cap_exceeded without charging. It does not mention credential/permission requirements or how to abort a started run (stop_run exists), leaving a small gap.

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?

Reasonably front-loaded: the verb, the precondition, then the delivery options, then costs, then the workflow. Slightly penalized for a redundant lowercase 'run extraction' lead-in that merely restates the title, plus inline markdown anchors that add noise without 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 an async, non-idempotent, credit-charging tool with no output schema, the description supplies everything the agent needs: that it returns a run object, the exact follow-up calls to obtain the records, the shape of the returned records (array of JSON objects matching the caller's schema), and the webhook escape hatch.

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 still earns a bump by explaining what `variables` actually does — filling `{{ placeholder }}` values with concrete examples like a search term or location — and by framing `webhook_url` as the delivery alternative to polling. `max_credits` and `estimate_cost` are left entirely to their schema text.

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

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

The first content sentence is a specific verb+resource: 'Execute a `ready` extraction', and the workflow line names the async run being started. It implicitly distinguishes itself from create_extraction by requiring an existing `ready` extraction, so an agent knows this is the execute step, not the authoring step.

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

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

Explicit workflow routing: 'poll `get_run`, then fetch the records with `get_run_result`', or alternatively 'pass a `webhook_url`'. The prerequisite (`ready` extraction) is stated. It stops short of telling the agent when to prefer webhook vs polling, or when to price first via estimate_cost, but the alternatives 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two genuinely useful traits beyond that: the counts are all-time (no date filtering) and they are an account-wide snapshot, which sets expectations about freshness and scope. It stops short of describing the response shape (e.g., per-status buckets) or any refresh/rate behavior.

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

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

Two short sentences plus a title line; the substance (all-time counts, use the other endpoint for records) is front-loaded with no filler. The embedded markdown REST link is slightly off-register for an MCP tool description and adds a small amount of noise an agent cannot act on.

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 zero-parameter, non-destructive aggregate with no output schema, the description covers what it does, its scope (all-time, account-wide), and where to go instead for detail. What it returns is implied ('counts by status') rather than spelled out, which is a minor gap given no output schema exists to fill 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. The description reinforces this by making clear the result is unfiltered and all-time, so an agent will not go hunting for a date or status argument.

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 resource and aggregation: 'All-time run counts by status — a snapshot of the account's run queue.' That clearly distinguishes an aggregate summary from the individual-run tools. It loses a point because the first line just restates the title, and the contrast is drawn against a REST endpoint ('GET /runs') rather than the sibling tool `list_runs`, which is what an agent actually has to choose between.

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

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

It gives an explicit alternative: 'For the runs themselves use ... ?status=...', which tells the agent to go elsewhere for per-run records. There are no exclusion conditions stated beyond that (no mention of time windows, account scoping caveats, or when the summary is stale), and the alternative is named as an HTTP path instead of the MCP sibling.

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

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

Annotations already flag openWorldHint and non-idempotency, and the description layers on context they cannot carry: synchronous versus run-polling semantics, per-call credit pricing tiers (0.30/0.10/0.01), proxy blocking risk, cache-hit behavior, and the fact that the response uses the legacy request_status format.

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

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

Front-loads the core synchronous-distinction sentence, then organizes secondary detail into labeled sections (example, credits, proxy, caching) that are easy to scan. The embedded curl example is useful for an HTTP-style API but adds length that a strict reader could call excess.

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

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

Covers the operational essentials: sync execution, credit costs, proxy necessity, caching, and the legacy response format. Since there is no output schema, a brief note on the returned fields beyond 'legacy request_status format' would have closed the last 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 baseline is 3, but the description adds real meaning beyond the schema for proxy_country_code (why you need it, with example codes) and skip_cache (tied to credit savings), plus cost implications for the request overall. max_credits and estimate_cost are left entirely to the schema.

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

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

States a specific verb and resource ('Scrape a webpage and return the text content') and explicitly differentiates from every run-based sibling by calling itself 'the only endpoint here that doesn't return a run to poll.' An agent can immediately tell this apart from run_extraction, get_run, or get_run_result.

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 conditional guidance inside the tool: use a proxy when the target may block or require geo, set skip_cache when freshness matters. It does not name alternative tools (e.g. run_extraction for structured extraction or quick_search) as the path to choose when scraping is not the right call, leaving that inference to the agent.

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

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

Annotations only declare openWorldHint=true and readOnlyHint=false; the description goes far beyond them by disclosing the long-poll behavior (up to `wait` seconds, default 50), the `status: processing` / `output: null` fallback and the polling endpoint to use, the `"not found"` sentinel for unanswerable questions, and credit accounting (1 credit charged on completion, failures not charged). These are exactly the operational facts an agent needs and none are inferable 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?

Content is front-loaded: the one-line purpose, then scope boundary, then the long-poll mechanics, then credits. It is somewhat heavy for a single tool — a curl example plus two JSON examples partially duplicate each other — but each block carries distinct information, so the length is defensible rather than padded.

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

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

With no output schema present, the description takes on the return-value burden and discharges it: it specifies `output.result` as free text or a schema-conforming object, the non-terminal `status: processing` state, and the `"not found"` string. Combined with the polling and credit details, an agent can call this correctly and handle every documented outcome.

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 above that by explaining the effect of `output_schema` on the return value (structured object in `output.result` instead of free text) and the wait/poll tradeoff, both of which are behavioral rather than mere restatements. `run_key` idempotency and the `max_credits` ceiling are only covered by the schema, so it stops short of a 5.

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

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

The body states a specific verb+resource ("Ask a question and get an answer") and explains the underlying mechanism: an AI + web-tool loop doing web search, scraping, PDF reading, and HTTP requests with no enrichment setup. It differentiates itself from the `enrich/` endpoint, but the leading "search agent" line merely restates the title, and it never distinguishes itself from the sibling `quick_search`, which an agent could easily confuse it with.

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

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

It gives an explicit usage boundary ("quick, relatively scoped one-off questions") and names the alternative for the other case ("For more complex questions, use the `enrich/` endpoint"). However, no guidance covers when to pick this over the closely related `quick_search` or `scrape` siblings, leaving a real routing ambiguity unresolved.

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=false and readOnlyHint=false, but the description adds genuinely new behavioral facts: the stop is irreversible ('cannot be resumed after stopping'), finished runs are unaffected, and the response is the run object either way. That last point substitutes for the missing output schema, which is real added value.

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 facts are front-loaded, but the tool name is restated three times ('stop run', 'Stop a run early', '**Workflow:** Stops a running run'), so a meaningful fraction of a short description is redundant. The irreversibility note is well placed.

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

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

For a single-parameter mutation tool whose annotations already flag destructiveness, the description covers the irreversibility, the no-op case, and the return shape. Nothing an agent needs in order 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?

Only one parameter, fully documented in the schema ('The run id (run_...)'), and the description adds nothing about id format or sourcing. With 100% schema coverage 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?

States a specific verb and resource ('Stop a run early') and explicitly scopes it to every run type, which is enough to separate it from siblings like get_run or list_runs. It does not name any sibling it must not be confused with, 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?

The description implies when to use it (a run is currently running) and clarifies what happens if the run already finished ('left untouched'). However, it never names an alternative such as get_run to check status first, nor does it state prerequisites or exclusions explicitly.

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

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

Annotations only say destructive/idempotent=false/readOnly=false; the description goes far beyond by disclosing that prompt/schema/tool edits turn existing cells `stale`, that rename keeps cells while delete drops them from reads, that added input columns read empty, that index_column re-keys every row, and that a 409 `dataset_in_use` occurs during a running fill. It also explains the copy-on-write safety net for shared enrichments, which is exactly the kind of consequence an agent needs before mutating.

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 spec paragraph followed by four examples that each demonstrate a distinct, non-redundant capability. The opening paragraph is very dense — heavy backticking and semicolon chaining make it hard to scan — and the fourth example's `Ticker`/`Website` payload only obliquely demonstrates the stated dedupe behavior.

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 tool with deep nested objects, the description covers mutation semantics, budget rules, pinning behavior, and conflict errors thoroughly. It never states what the tool returns on success, which matters slightly more here because no output schema exists 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 100% schema coverage the baseline is 3, but the description adds semantics the schema only implies: the 1.5-credit-per-column budget drift, `budget_locked` winning over that adjustment, and type inference on added output columns. The four worked examples concretely demonstrate nesting and operation combinations (`{}`, `rename`, `delete`, `tool`, `null` unpin).

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 — 'Edit a dataset's structure (no run)' — and immediately scopes it to name, index_column, input_columns, output, budget. The parenthetical '(no run)' plus 'Then enrich with dataset_id' cleanly separates it from enrich and update_enrichment, whose names alone would otherwise make the boundary ambiguous.

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 real workflow routing: use this first, then call `enrich` with `dataset_id`, and points to `help` with `datasets`, `pinned_columns`, `output_schema` for deeper reference. 'Edits a shared enrichment on a private copy' hints at when to prefer `update_enrichment` instead, but never names that sibling or states the exclusion explicitly.

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 a destructive, non-idempotent, non-read-only mutation, the description adds substantial context: 422 for an index-column value another row holds, 409 `row_in_use` for `input` during a fill, `cells` landing regardless, and `null` reverting to `pending`. This is exactly the kind of error and side-effect disclosure the 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?

The operative scope statement is front-loaded and every sentence carries new information (error codes, state transitions, force behavior). It is terse to the point of telegraphic style in places, but there is no filler to cut.

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 nested-object mutation with no output schema, the description covers the important behavioral edges: partial success, error codes, and value lifecycle. It stops short of describing the response or confirming what the manual cell looks like after success, 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. The description goes beyond the schema by explaining the `input` versus `cells` split (input columns vs output columns), the manual-vs-pending state transition on `cells`, and that `force` governs whether fills overwrite a manual cell — semantic value not present in the property descriptions.

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

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

The description states a specific verb and resource: "Write one row (`row_id`...)" by hand, and clarifies it sets both input and output cells in one write. It implicitly distinguishes from bulk siblings (`add_dataset_rows`, `import_dataset_rows`) via "by hand" but never names them, so it doesn't fully earn 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 implied rather than stated: the agent learns that `input` writes are blocked while a fill runs, that `cells` writes are manual and can be cleared with `null`, and that `force` affects retention. There is no explicit when-to-use-this-vs-alternatives guidance (e.g. versus `add_dataset_rows` or `build_dataset_rows`), so it lands at implied usage.

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 important side effects: budget movement by 1.5 per column, `budget_locked` behavior, changed cells becoming `stale` until the next `enrich`, tool-pinning semantics, rename behavior, and deletion of columns. These details materially help an agent understand the destructive and non-idempotent nature already flagged 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?

The description is dense but appropriately sized for a complex nested mutation, with the core behavior front-loaded before the examples. It could be tightened slightly because the opening 'update enrichment' is tautological and the `help` references are repeated.

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 nine-parameter nested mutation with no output schema, the description covers the editable surface, important side effects, conflict behavior, and practical examples. The annotations and rich schema descriptions carry the remaining structural details, so an agent has enough context to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds operational meaning beyond the schema: how `budget` interacts with column changes, how `output` entries add/change/rename/delete columns, and how tool pinning produces one call per row. The examples further clarify nested `output` usage, though some parameter detail is duplicated from 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 uses a specific verb and resource: 'Edit an enrichment,' then enumerates the exact editable fields, including nested output-column edits. It also distinguishes this tool from the sibling `update_dataset`, which handles changing one dataset's columns.

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

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

It explicitly routes one alternative case to `update_dataset` and warns that a 409 `enrichment_in_use` occurs while a fill runs. However, it does not fully state when to use this versus `create_enrichment`, `delete_enrichment`, or `get_enrichment`, so it 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 it non-readonly, non-destructive, non-idempotent and open-world. The description adds genuinely useful behavior beyond that: `null` means every column, and null is refused on monitors on a legacy enrichment (response carries `legacy`). It doesn't state auth/permission needs or reversibility of a column reset, so it stops short of 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?

Front-loaded one-liner followed by precise parameter-to-behavior mapping, then examples. Three JSON examples are somewhat redundant (pause/resume are trivially obvious) but they remain short and directly illustrative, so nothing is egregiously 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?

All four parameters are covered, the legacy refusal edge case is documented, and with no output schema the description needn't explain returns. The absence of any note on permissions or the shape of a successful update response 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 baseline is 3. The description adds real meaning beyond the schema: semantics of `null` for `columns`, the legacy-enrichment refusal rule, and the pause/resume semantics of `enabled`. `webhook_url` is only described as a replacement, matching the thin schema description.

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

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

The first line names the specific verb (update) and resource (monitor), then enumerates the three concrete operations: pause, resume, repoint. An agent can tell this apart from create_monitor/list_monitors/get_monitor 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 explicitly maps each parameter to a behavior: `enabled: false` pauses, `enabled: true` resumes, `webhook_url` replaces the delivery URL, `columns` changes filled columns. It gives clear operational context but does not name when to prefer a sibling or list preconditions/exclusions.

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