Mostly Right

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

Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: it explains that the tool refuses if expected_version doesn't match, that any workspace editor can call it, and that it answers step_up_required for REPAIR holds. It also states the return format (run receipt). No contradictions with annotations.

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

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

The description is dense but every sentence contributes to usage, exclusions, parameter meaning, permissions, and follow-up. It is front-loaded with the core purpose and conditions, then flows logically. It could be slightly trimmed (e.g., the REPAIR explanation), but it remains efficient and well-structured.

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

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

For a niche legacy tool, the description covers when to use it, when not to, how to pass the correct expected_version, permission context, the REPAIR hold exception, the return value, and the next recommended step (run_events). No output schema exists, but the description states the return type. This is a complete and actionable definition.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains expected_version thoroughly: 'Pass expected_version from the get_run that showed you the preview, so a run that moved in between is refused rather than released.' It also provides an example with both parameters. run_id is self-explanatory as the run to approve, though not explicitly described; the example clarifies its usage.

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

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

The description clearly states the tool's purpose: to release a legacy preview hold for an existing full run. It distinguishes from new full builds and REPAIR holds, making the function unambiguous and easily differentiable from siblings like confirm_run.

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

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

The description gives explicit conditions for use: 'Call it ONLY once the legacy preview has sealed a table you have checked and the user has said to build the whole thing, or on a delegation you recorded with write_note.' It also explicitly excludes new full builds and REPAIR holds, stating the alternative (a person in a signed-in browser) for REPAIR holds. This is comprehensive 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 cover the safety profile (readOnly=false, destructive=false, idempotent=false), but the description adds real behavioral context: which run states are cancellable, that a gate-cancelled run never ran, that it returns a receipt with status cancelled, and that finished runs reject the call. It stops short of stating what happens on a repeated cancel of an in-flight run, which idempotentHint=false makes relevant.

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

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

Four short sentences, front-loaded with the core action and states before the example and the error case. The embedded JSON example is compact and earns its place by pinning run_id, though it borders on redundant with the schema.

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

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

With no output schema, the description correctly describes the return (run receipt with status cancelled) and covers the failure path. The only real gap is the undocumented expected_version parameter and the repeat-cancel behavior implied by idempotentHint=false.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. The inline example documents run_id's shape, but expected_version (an optimistic-concurrency integer) is never mentioned in either the schema or the description, leaving one of two parameters fully unexplained.

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 (stops/cancels) and resource (a run), and enumerates the exact states it applies to (queued, held at the confirmation gate, running). An agent can distinguish this from start_run, get_run, and confirm_run 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?

Explicitly names the conditions for use (queued, at gate, running) and the when-not case (already finished) plus the correct alternative (read get_run rather than retrying). This is exactly the when/when-not/alternative guidance the dimension asks for.

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 itself is highly transparent about snapshot incompleteness and disposition behavior, but it declares 'a miss is NOT evidence that no such source exists' while the annotations set openWorldHint=false. That encodes the opposite closed-world assumption, so this is an annotation contradiction and per the scoring rule must receive a 1.

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 a clear purpose and critical warnings, but it is very long and includes repetition around trustworthiness, format behavior, and field nullability. Every sentence has value, but the overall length makes it harder for an agent to scan quickly.

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 there is no output schema, the description fully covers the response envelope (status, question, requirement, generation, candidates, work), candidate fields and null semantics, ordering and the absence of relevance scores, error formatting for malformed arguments, and the credential requirement.

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

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

With 0% schema description coverage, the description compensates by explaining the format parameter semantics (single token, withholds nothing, one per question), the validation before the actual call, and the example call. The limit parameter is not deeply described beyond defaults and validation, which keeps it from 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 description states a specific action and resource: search a sealed snapshot of public data sources for feeds that might answer a question. The phrase 'first move when you need a source and do not already know one' clearly frames its role relative to other tools.

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

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

The description explicitly tells when to use the tool (when you need a source but do not know one) and gives an invocation example. It does not name alternatives or state explicit when-not-to-use conditions, so it falls just short of full 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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false, but the description adds critical behavioral context: the numbers cannot be restated, the server authorizes its own projection, a stale expected_version causes a refusal rather than silent authorization, and it returns a run receipt. This is exactly the kind of safety and concurrency semantics annotations can't convey.

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

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

Front-loaded with the action and result, then quotes an example, then the concurrency rationale, then the human-approval prerequisite. Dense but every clause carries information; the human-approval sentence at the end could be earlier, but the ordering still works.

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, so the description correctly states the return ('run receipt with its new status'). Covers all required behavior: prerequisite, concurrency guard, immutability of inputs, and return value. Complete for a two-parameter mutation tool.

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

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

Schema description coverage is 0%, so the description must compensate and does: it gives a concrete example object, explains that the numbers are server-stored and not user-restatable, and tells the agent to pass expected_version from get_run. This adds substantial meaning beyond the bare JSON Schema, which only provides types and format constraints.

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 (authorizes) and resource (a held run) and immediately clarifies the semantics: it starts the run and uses server-stored numbers. Distinguished from siblings start_run, cancel_run, and get_run by the 'held run' framing and the authorization intent.

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

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

Explicitly says 'Only call this after a person has seen the projection and agreed to it', which is a clear prerequisite. It also directs to pass expected_version 'from the get_run that showed you the projection', routing the agent to the right sibling and sequencing. No ambiguity about when 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?

Beyond the annotations, the description discloses idempotent behavior ('reports already_connected'), required role, required OAuth scope, the mr_use_ key restriction, side effects ('grants the workspace read access'), and non-effects ('does not change the dataset or cost anything'). This is rich behavioral disclosure well beyond the structured fields.

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

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

The description is dense but mostly purposeful: it front-loads the main action, then covers idempotence, roles, auth, and side effects in sequence. The phrase 'and refuses with the two routes that do work' is awkward and slightly confusing, but the overall structure is efficient and every sentence contributes useful 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 one-parameter, idempotent connection tool, the description covers purpose, prerequisites, auth, side effects, and idempotent outcomes. With no output schema, it would benefit from a brief statement of what a successful response contains beyond 'already_connected,' but the available context is otherwise sufficient for correct invocation.

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

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

Schema coverage is 0%, so the description must carry the load. It provides a concrete JSON example mapping dataset_slug to 'kden-metar-hourly' and clarifies the parameter identifies a public dataset. It does not explain how to discover valid slugs or whether a slug must exist beforehand, but for a single string parameter the example adds meaningful semantics.

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 ('Connects'), a specific resource ('one public dataset'), and the concrete outcome ('its tables become queryable and downloadable'). It also positions this tool as 'the gate every keyed read passes,' which distinguishes it from read and listing siblings like get_dataset and list_connected_datasets.

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 clear usage context: this is required before keyed reads work, and it explicitly states who can use it (Owner/Admin/Editor) and which credential types are allowed or forbidden. It does not explicitly name an alternative like list_connected_datasets for checking existing connections, so it stops just short of full when-not-to-use 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 cover the safety profile (readOnlyHint false, destructiveHint false, idempotentHint true), and the description adds substantial context beyond them: 'Costs nothing to run and builds nothing,' the reuse behavior returning an existing empty dataset with reused_open_request: true, and the fact that the given name is a working title replaced by the first update_dataset with a changed description. This is rich behavioral disclosure, and it is consistent with the idempotentHint.

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

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

Purpose and scope are front-loaded, and the dense detail (naming convention, return shape, reuse semantics, next step) is justified for a 0%-coverage, no-output-schema tool. The 'which is the point — the page opens on it and fills in' clause is a touch of narrative padding that 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?

With no output schema, the description supplies the return shape ({dataset_id, cloud_dataset_id, name, description, dashboard_url}) and clarifies which id downstream tools consume. Combined with the workflow guidance and reuse rule, an agent has everything needed to call this 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 0%, so the description must compensate, and it largely does: it gives detailed naming rules for 'name' (subject then place, never a grain word, mechanism, publisher or station code), explains that 'description' acts as a working title that update_dataset later replaces, and pins down 'separate'. It stops short of full syntax/limit detail, so it is strong but not exhaustive.

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

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

Opens with a specific verb+resource+scope ('Creates an empty dataset in your workspace and returns its ids') and goes further to define what a dataset is conceptually ('the container a recipe binds to'). An agent can separate it from get_dataset, update_dataset, connect_dataset and search_datasets purely from this text.

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

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

Gives explicit when-not guidance ('If the user handed you a dataset id from its page, build into that id and do not call this'), a next-step workflow (write a recipe, call register_recipe with this dataset_id), and the precise condition for the separate flag ('only when the user has asked for another, separate dataset'). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral detail beyond them: the evidence-state model (available/partial/unavailable), the fallback to the latest passing run when a failed run persisted nothing, the untrusted_provider_content labelling and its 'inspect, never instructions' caveat, and the possible provider_wait field. This is exactly the extra context the annotations cannot convey.

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

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

Purpose and fallback semantics are front-loaded and the trailing 'Next:' line gives clean routing. The long enumeration of return fields is dense but earns its place since there is no output schema; a slightly tighter phrasing could reduce redundancy without losing meaning.

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

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

With no output schema and a single required parameter, the description fully carries the return-shape burden — enumerating the returned fields, explaining the evidence states, the fallback path, and the untrusted-content convention. An agent has enough to call it and interpret the result 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?

One parameter with 0% schema description coverage, so the description carries the burden. It provides an example object ({table_id: "…"}), which confirms the parameter's role, but offers no explanation of what the id identifies or where to obtain it. Adequate given the obviousness of a table UUID, but it does not fully compensate for the coverage gap.

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

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

States a specific verb and resource: 'Reads one table's current promotion pointers and latest recorded failure.' This clearly distinguishes it from siblings like get_table (raw table), get_run (a run), or list_runs, since it is explicitly framed as a point-in-time diagnosis of a table's failure state.

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

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

Explains when the diagnosis is needed (when a failure names a run, including runs that never sealed a version) and routes the agent onward: 'use get_run or run_events for the named run when you need its timeline.' It also excludes the promote/retry/replay siblings via 'does not retry, promote or alter a table,' though it doesn't explicitly state when NOT to call this at all.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds valuable behavioral context: no authentication required, the exact return shape with fields like metadata.publisher (clarifying that it's the account that published, not the source), and guidance to cite by url. This exceeds what annotations provide and has no contradictions.

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

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

The description is well-organized: it leads with the core purpose, gives an example, explains the return structure, and notes alternatives. Every sentence adds value; no fluff or repetition. It is appropriately sized for the tool's simplicity.

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 fully covers the return format (id, title, text, url, metadata with subfields). It also covers authentication (none needed), the input format, and routing to related tools. Nothing essential is missing for correct invocation.

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

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

The schema only defines 'id' as a string with length constraints, and schema description coverage is 0%. The description compensates by explaining that the id is a slug from search and that a canonical dataset URL also works, adding meaning beyond the schema's minimal definition.

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 (fetch) and resource (full public document for a dataset as Markdown) and clearly distinguishes itself from siblings by naming get_dataset and get_table_schema for machine-readable table ids and schemas. The purpose is unambiguous and differentiated.

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

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

It explicitly says 'No account needed,' provides an example with a slug, and notes that a canonical dataset URL also works. It also states when to use alternatives (get_dataset and get_table_schema) for machine-readable data, making usage guidance explicit.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds useful behavioral context: the optional dataset_slug returns a link to the dataset page where a key is minted, and the tool's role is purely informational. No contradictions with annotations.

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

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

Three sentences each serve a distinct purpose: describing content, explaining the optional parameter, and stating when to call. The opening sentence is a dense list but not bloated; every part earns its place.

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

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

For a tool with one optional parameter, no output schema, and safety-bearing annotations, the description covers what the tool returns, how the optional parameter changes behavior, and when to invoke it. No critical information is missing.

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

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

The only parameter, dataset_slug, is named, marked optional, given an example value ('kden-metar-hourly'), and its effect is clearly explained. This fully compensates for the 0% schema description coverage.

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

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

The description clearly identifies the tool as returning access instructions: what is anonymous, what needs an account, API key classes, OAuth, signup URL, and numbered steps. It is specific and distinct from data-fetching siblings, though it does not explicitly name a sibling or contrast itself with other instruction tools.

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

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

It gives explicit trigger conditions: 'Call this whenever a tool refuses for want of authentication, or before telling a user they need to sign up.' This is strong situational guidance, but it does not mention when not to use the tool or name alternatives.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive Button. The description adds non-obvious behavior: the URL expires and the caller must fetch it themselves. This is valuable beyond the structured annotations, though it doesn't specify the exact expiry duration.

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?

Five concise sentences, each carrying information: what it does, how to consume it, an example, return shape, cross-reference, and a cheaper alternative. Front-loaded with the core action and constraints.

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

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

Despite having no output schema, the description enumerates the returned fields and summarizes the mechanics (short-lived URL, plain GET, no headers). It also addresses cross-tool data flow (run_artifacts) and alternative tool selection (query_run). An agent has everything needed to call it correctly.

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

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

The schema documents parameter names and types at 0% description coverage, and the description compensates with a concrete JSON example plus the provenance clue that artifact_id values come from run_artifacts. It doesn't fully explain run_id's source, but the example plus schema types make it usable.

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:

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 usage context: fetch the URL with a plain GET, no headers, it is short-lived; and explicitly says not to use this for reading a few rows, pointing to query_run as the cheaper alternative. It also tells where artifact IDs come from (run_artifacts), which eliminates a common caller mistake.

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 provide read-only, idempotent, and non-destructive signals, so the description only needs to add operational context. It adds clarity around immutable version_id, the meaning of publisher, and the precise boundary of the response, though it does not cover failure or auth behavior—minor for a metadata read.

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-loads the output contents, then adds the publisher clarification, parameter example, and sibling routing. It is long but every sentence carries new information; a bullet list could improve scannability, but there is no real waste.

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

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

There is no output schema, but the description enumerates the key response fields, names the excluded fields and where to get them, and explains how to use returned identifiers with downstream tools. For a single-parameter read operation, this is complete enough for an agent to invoke it successfully.

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

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

With 0% schema description coverage, the description must compensate for the single slug parameter. The concrete example, kden-metar-hourly, combined with the overview context, makes it clear that slug is the dataset identifier, though it does not fully explain where the slug comes from or how to resolve it.

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

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

The description states exactly what this tool returns: an overview for one dataset, including tables and their key metadata, while explicitly excluding schema details. It clearly differentiates the tool from get_table_schema by naming which fields belong to that sibling, so an agent can select it without opening schemas.

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

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

It gives explicit routing guidance: use get_table_schema when column types, descriptions, units, or published profiles are needed, and use the returned table id with get_table_schema, sample_rows, and query_table. It does not, however, explain when get_dataset should be chosen over the similarly named get_my_dataset or get_table siblings.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds important behavior: it returns a request to make yourself rather than data, includes whether the publisher enabled downloads, and explains the workspace key requirement. It accurately aligns with the non-destructive, read-only annotations.

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

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

Three concise sentences front-load the exact return value, then provide an example, a key behavioral distinction, and an auth note. Every sentence adds necessary information without redundancy or 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?

Given the single parameter, no output schema, and rich annotations, the description is complete: it covers what is returned, how to authenticate, the non-streaming behavior, and when to prefer this tool. An agent has everything needed 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?

The schema has no descriptions for the single table_id parameter, but the description compensates with context and an example. It makes clear the parameter identifies the table whose Parquet snapshot download instructions are being requested, which is sufficient for one obvious UUID 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?

The description names a specific verb and resource: it returns the exact URL, HTTP method, and header for downloading a table's immutable Parquet snapshot. It also distinguishes the tool from query_table by explicitly saying this is preferred over paging a whole table, and clarifies this is not a streaming data tool.

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 directs the agent to prefer this tool over query_table for snapshot downloads, and explains that bytes are never streamed through MCP. It also states the authentication prerequisite (mr_use_ workspace key) and that the result includes how to obtain one, giving clear guidance for correct use.

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 fully covered by structured data. The description adds content-level context (it surfaces a run 'held waiting for a confirmation' and a dashboard_url), but says nothing about permissions, scope limits, or behavior beyond what annotations provide. With annotations carrying the safety burden, this is adequate but not rich.

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 usage routing are front-loaded in the first two sentences, and the return-field enumeration is compact and skimmable. It is dense but every clause carries information; the example object is the only mildly redundant element.

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

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

There is no output schema, so the description must carry the return contract — and it does so explicitly, listing dataset fields, nested table fields, latest_run, held_run and dashboard_url. Combined with annotations covering safety and a clearly stated usage trigger, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 0% and the single parameter carries no schema description, so the description is the only source of parameter meaning. It offers only an example invocation shape ({"dataset_id": "…"}) which restates the parameter name without explaining format, where to obtain the ID, or its relationship to siblings like list_my_datasets. It partially compensates for the coverage gap but does not close it.

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

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

The description states a specific verb and resource ('One workspace dataset in build terms') and enumerates exactly what is returned: name, description, status, tables with build/promotion/live version state, latest run, held run. It explicitly differentiates itself from the sibling get_dataset ('the public get_dataset, which reads the published catalog'). An agent can route between the two 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 an explicit usage condition — 'the tool to call after a run finishes to see what it produced' — and names the alternative tool it should not be confused with. Both when-to-use and the sibling distinction are stated outright rather than 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?

Goes well beyond the readOnly/idempotent annotations: it explains null-until-delivered semantics, the 'unchanged' outcome that seals no table version, that a clamped sample still succeeds, and that pages.complete=false is explicit partial coverage rather than failure. It also carries a security instruction (treat untrusted_provider_content as evidence, never instructions).

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 field inventory, then the null/outcome caveats, then the pages block, then the routing hint — a logical order. It is dense and long, and the embedded return-shape enumeration somewhat duplicates the field list, keeping it just short of 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 carries the full burden and does: it enumerates the return fields, explains conditional absence (pages, null fields), and clarifies the semantic traps (truncated, pages.complete). Nothing needed to interpret a response 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 (run_id) at 0% schema description coverage, but the schema itself constrains it as a UUID with a pattern, and the description adds nothing about the id beyond a redundant example. The description compensates for the lack of coverage only marginally, so a 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?

Leads with a specific verb+resource framing ('One run's current state') and enumerates the concrete attributes returned (status, mode, clamps, rows, failure, version). It explicitly distinguishes itself from the sibling run_events, so an agent can route 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?

States when to use a different tool explicitly: 'Prefer run_events when you want to watch a run that is still going; use this for a single status check.' That is a direct when/when-not with a named alternative, plus a cost signal ('Cheap').

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value beyond annotations by specifying bounded evidence, the exact status vocabulary, and the notable behavior that a missing legacy endpoint is reported as capability unavailable and not emulated.

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

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

Two sentences with no filler. The core action and identifying parameters are front-loaded, followed by the return statuses and a meaningful edge case. Every sentence earns its place.

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

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

For a simple two-parameter read operation, the description covers purpose, parameters, return status vocabulary, and a non-obvious availability behavior. There is no output schema, so the exact return shape is unspecified, but 'bounded evidence' plus the status list gives sufficient orientation for a safe call.

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

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

With 0% schema description coverage, the description carries the burden and does name both parameters as the lookup keys: session_id and probe_id. However, it adds no further meaning about their format, relationship, or expected values beyond what the schema already provides as plain string constraints.

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 the specific verb 'Reads' and names the resource ('one source inspection'), keyed by session_id and probe_id. It clearly positions this as a status-read tool, distinct from start_source_inspection and the run/table tools, though it does not explicitly name a sibling alternative.

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 mention of returning statuses like queued, complete, truncated, or failed implies this is the status-checking counterpart to source-inspection orchestration, but it does not explicitly say when to use this tool over related tools or when not to use it. Usage context 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 already declare readOnly/idempotent/non-destructive, but the description adds materially more: the return shape, the fact that last_failure carries code/stage/run/timestamp but not the provider's words, and the untrusted_provider_content contract with an explicit prompt-injection warning. That security-relevant disclosure is not derivable from 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 purpose, then return shape, then the untrusted-content caveat and id provenance. The prose is dense and long, but nearly every sentence carries operational information; only the 'same shape on every tool' aside is arguably redundant here.

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, so the description's enumeration of returned fields and the special handling of last_failure versus untrusted_provider_content is exactly the missing information. Combined with id provenance, an agent has everything needed to call and interpret the tool.

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

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

With 0% schema description coverage the description must compensate, and it partially does by giving an example payload and by documenting where valid table ids originate. It omits format/validity expectations (UUID) that the schema enforces, so it adds meaning but not full 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?

States a specific verb and resource ('one table as the builder sees it') and enumerates exactly what is surfaced: promotion status, live version, refresh schedule, learned rhythm, last refresh and last failure. This is clearly distinguishable from list_tables, get_table_schema, query_table and diagnose_table.

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 tells where table ids come from (register_recipe, get_my_dataset, a run receipt), which is useful operational guidance, but it never says when to call this instead of siblings like diagnose_table, get_table_schema or query_table. Usage context 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 already cover the read-only and idempotent nature, so the description adds the valuable behavioral constraint that the listed column names are the only ones the query grammar accepts, plus the immutability of version_id. This goes beyond what annotations alone convey.

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

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

Three sentences accomplish a lot: they enumerate the return contents, provide a concrete example, and give a critical usage rule. There is no redundancy, and the most actionable warning is placed at the end where it stands out.

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, single-parameter tool, the description thoroughly covers what is returned, the parameter example, and the critical interaction with query_table. Minor omissions like response format or error behavior are acceptable given the simplicity and annotations.

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 only one parameter and the schema description coverage is 0%, so the description carries the full burden. It supplies a concrete UUID example and contextualizes the table, but it never explicitly defines table_id as the table identifier, leaving some meaning implicit in the title and example.

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 specifies the resource (one table) and the exact output shape (columns with type/profile and capabilities), and it calls out the query_table sibling by name, making the tool's role unambiguous.

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

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

It gives a concrete, actionable usage instruction—'Read this before writing a query_table call'—which is a strong when-to-use signal. It does not enumerate other sibling alternatives, but it effectively coordinates with the most relevant one.

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

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

Annotations already declare the safe, read-only, idempotent, non-destructive profile. The description adds useful behavioral context beyond annotations: it specifies the exact return shape, explains that an empty list means nothing has been used yet, and clarifies that query_table can connect datasets on first use.

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 tool's purpose, followed by no-argument confirmation, the important query_table caveat, return shape, and empty-list semantics. Every sentence adds useful information without waste.

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

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

With no output schema, the description provides the return object structure and the meaning of an empty list. Combined with annotations covering the safety profile and the explicit no-argument note, it is complete enough for an agent to call the tool correctly.

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

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

The tool takes no parameters, so the baseline is 4. The description confirms 'Takes no arguments,' which is consistent with the empty schema and adds no ambiguity.

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 resource and scope: the public datasets the authenticated workspace has used so far. It differentiates itself from query_table and connect_dataset, but does not explicitly distinguish itself from the sibling list_my_datasets.

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?

Clearly explains that query_table is not limited to this list and describes how key and OAuth connections access datasets, which helps the agent avoid treating this list as a prerequisite. However, it does not explicitly say when to choose this tool over list_my_datasets or other listing tools.

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 readOnlyHint annotation by explicitly stating it is a cheap database read with no backend call, and it documents the return shape (workspace_id, datasets array, count). It doesn't mention failure modes or pagination, but the core behavioral contract 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 concise and information-dense: ordering, scope, use case, example, and return shape are all covered in a few sentences, with the core meaning stated first.

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 what is returned, the ordering, scope, and gives a concrete request example. It does not mention error cases or pagination beyond the limit example, but for a list endpoint with a simple schema this is reasonably 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 schema provides no description (0% coverage), and the description includes a usage example with 'limit': 25. However, it never explicitly states that limit controls the number of datasets returned; the agent must infer this from the parameter name and min/max bounds.

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: 'List ALL datasets in this workspace', explicitly scopes to owned datasets, distinguishes from the public catalog, and clarifies it returns datasets created by the user or colleagues. This clearly separates it from siblings like get_my_dataset or search_datasets.

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 clear usage scenario ('Use it to find the dataset_id for a dataset you or a colleague created earlier') and an exclusion ('not the public catalog'). It does not name an alternative tool explicitly (e.g., search_datasets for public datasets), so it falls just short of full 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond that: pagination behavior ('complete false means the walk stopped at its page cap'), storage ordering ('runs are not stored in time order'), and relative cost ('most expensive read here'). This transparency meaningfully informs an agent about side effects, limitations, and performance.

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 packs a lot of information into a tight, forward-loaded structure: scope/ordering, optional filters, an example, return shape, and a critical performance warning. Every sentence serves a purpose; there is no filler or redundancy.

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

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

For a 4-parameter list tool with no output schema, the description fully covers the return format ({runs: [...], count, complete}), explains the complete flag and its implications, gives a concrete example, and communicates the cost/ordering caveat. An agent has everything needed to call it correctly and interpret results.

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 0% in the structured sense, but the description explicitly mentions all four parameters (dataset_id, status, mode, limit) and adds semantics: 'narrowed to one dataset, one status or one mode' and the example clarifies usage. It does not fully explain limit's role beyond the example and the page-cap reference, but it adds enough value over the enum schemas.

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 this workspace's runs', and adds scope ('workspace's own') and ordering ('newest first'). It also clarifies the narrowing options (dataset, status, mode), which distinguishes it from get_run, run_events, and query_run. The title and description are consistent, and the example reinforces purpose.

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

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

The description gives clear when-to-use guidance: 'Use it to find a run_id you lost, or to see what a dataset has been doing.' It also warns when not to use a workspace-wide list ('ALWAYS pass dataset_id when you know it') due to cost and likely incompleteness. However, it does not explicitly name alternatives like get_run for a known run_id, so it stops short of full when-not 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: no secret ever crosses the server, the tool takes no arguments, and it returns a specific shape. It also discloses the limitation that credentials cannot be added by the agent, which is beyond the annotations.

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

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

The description is compact and front-loaded: it states the core purpose first, then the security guarantee, then the return shape, then usage guidance. Every sentence earns its place, and there is no redundant repetition of the title or annotations.

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

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

For a zero-parameter read-only tool, the description is complete. It covers what the tool returns, the security behavior, how to use the result, and what to do when the desired credential is absent. The output schema is absent, but the description provides the return shape explicitly, so nothing critical is missing.

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

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

The tool has zero parameters and schema coverage is 100%, so the schema fully documents the input. The description adds value by explicitly stating 'Takes no arguments' and describing the return shape, which helps the agent understand the tool's contract even though there are no parameters to clarify.

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 ('List') and resource ('source credentials this workspace holds'), and distinguishes itself from the broader sibling set by clarifying it returns credential names, not values. It also explains the relationship to recipes, which makes its purpose 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?

The description explicitly says when to use this tool: to learn which credential names exist for recipes. It also gives clear guidance on what to do if the needed credential is missing (ask the person to paste it at the paste_url) and what not to do (do not ask them to send it directly). This is strong usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it is a 'cheap call,' it omits column schemas, and it returns a specific shape with dataset_slug and an array of table objects.

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

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

Three sentences, no filler. The key scoping statement is front-loaded, followed by a concrete example, the return shape, and the sibling alternative. Every sentence contributes distinct information.

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

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

For a simple, single-parameter read-only list operation with no output schema, the description is complete: it gives usage context, a valid example, the exact return structure, and an explicit routing rule to get_dataset. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It provides a concrete example value ('kden-metar-hourly') and shows dataset_slug as part of the return shape. For a single, self-describing parameter, this is sufficient practical guidance even though it does not formally define the slug 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 and resource: 'The tables in one dataset,' and clearly distinguishes it from siblings by noting it omits full column schemas and returns only lightweight fields like table ids and titles. It also names get_dataset as the alternative when columns are needed, so an agent can tell the tools 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?

The description explicitly says when to use this tool: when you only need table ids and titles, and explicitly tells the agent to 'Use get_dataset instead when you also want columns.' This is direct, actionable guidance with a clear alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context: it validates only, does not decode bytes, returns default-filled canonical options, and lists the returned fields. No contradictions with annotations.

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

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

Three sentences, each carrying distinct information: what it resolves/returns, what it deliberately does not do, and the output fields. The most important constraint is front-loaded, and there is no filler.

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

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

The description is largely complete for a validation/read-only tool with annotations covering safety: it names return fields and explicitly scopes behavior. It lacks details on failure modes for non-certified families and how defaults are computed, but these are secondary given the no-output-schema context.

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

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

Schema description coverage is 0%, and the description does not explain the semantics of the three required parameters beyond their names. decode_options remains an opaque object, and the meaning of 'certified Reader family and version' is not elaborated. The schema regex provides some format guidance for family_version, but the description does not compensate for the lack of parameter documentation.

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

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

The description uses specific verbs 'Resolves', 'returns', and 'Validates' to define the tool's operation on the Reader family, and it explicitly distinguishes itself from data-acquisition tools by stating it 'does not acquire or decode bytes.' This makes its role clear against siblings like fetch, query_run, and get_table.

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

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

The description provides clear context by stating this is for the recipe and that it validates options only, implying it should be used before decoding or acquiring bytes. It does not explicitly name alternatives or exclusion conditions, so guidance is good but not fully explicit.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses that it refuses without confirm:true, that a promotion may trigger an oversized catch-up refresh, that the table is STILL PROMOTED in that case, and that the response carries held_run requiring confirm_run or cancel_run. This is rich, non-obvious behavioral detail.

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

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

The core purpose and confirmation requirement are front-loaded, followed by return shape and the catch-up edge case. It is dense but nearly every sentence earns its place; the catch-up/held_run passage is long but necessary to avoid a wrong follow-up call.

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

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

With no output schema, the description compensates by enumerating the returned fields ({table_id, promotion_status, live_version_id, cadence, dashboard_url}) and covering the tricky held_run branch and the confirm gate. Nothing critical for correct invocation appears missing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains confirm's semantics ('refuses without confirm: true') and shows table_id in the example, but the cadence parameter is never explained, leaving one of three parameters undocumented in both schema and prose.

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

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

The description states a specific verb (promote) and resource (table) and defines the operation's effect precisely: the newest passing version becomes the served one plus a recurring refresh starts. It is clearly distinguishable from siblings like start_run, which is explicitly named as not to call.

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

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

Explicit conditions are given: 'Only call it when the person you are working for has said to' and 'Check the data with query_run first,' plus the negative routing instruction 'Do not call start_run for it.' It names both prerequisites and the alternative tool to avoid.

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?

Far exceeds what annotations provide. Annotations declare it is not read-only, idempotent, and non-destructive; the description adds richer traits: it confirms no run, promotes no table, approves no repair, returns immutable coordinates, doesn't go live, and specifies the held/confirmation flow and a failure mode (revision_registered_replay_not_started). This is unusually complete behavioral disclosure with no contradictions.

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 dense with essential behavior, but several sentences are lengthy and mix concerns (flow, error handling, UI instructions). It is not bloated with filler, yet the wall-of-text structure reduces scannability for an agent.

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 no output schema and only 2 params (one nested, undocumented), the description compensates by specifying return fields ({recipe_id, recipe_digest, ...}), the held-return variant, and an error path. It covers the full operational lifecycle needed to call and follow up 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 0%, but the description compensates by providing a concrete example payload showing both required params ('recipe': {...whole revision document...}, 'sources_from_run': '...'). It still doesn't fully explain the recipe document structure or clarify that sources_from_run must be a UUID (covered by schema format). Baseline 3 is appropriate given the example adds context but leaves the recipe object under-specified in prose.

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

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

The description states a specific verb (registers a proposed revision) and resource, and explicitly distinguishes its behavior from siblings: 'starts EXACTLY ONE run: a replay of the named successful run's retained inputs', 'confirms no run, promotes no table and approves no repair'. An agent can identify it apart from replay_run, start_run, promote_table, and approve_full_run without opening schemas.

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

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

It provides clear when-to-use context (propose a revision; then confirm via confirm_run if held; re-propose after fixing preconditions) and names alternatives (confirm_run, approve_full_run, promote_table) it does not perform. No explicit when-not-to-use, but strong operational 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the 100-row max_rows cap, the 16 KiB trim with rows_omitted, the 20s wait_seconds cap, the query_timed_out/query_id continuation contract, and the untrusted_provider_content labelling with an all-caps instruction to treat it as evidence not instructions.

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 and dense with no filler — every clause carries a constraint, cap, or routing hint. It is long and em-dash-heavy, with the untrusted_provider_content note trailing at the end, but nothing is truly redundant.

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

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

Even without an output schema, the description enumerates the return shape ({query_id, state, rows, row_count, truncated, elapsed_ms, result_digest}) and the failure shape (query_timed_out), plus caps and the untrusted-content wrapper. An agent can call this and interpret the result without further sources.

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

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

Schema description coverage is 0%, so the description must carry the load and does: it defines sql's dialect and required leading keyword, max_rows' cap, wait_seconds' cap, and query_id's role as a no-sql continuation handle. run_id is only implicitly identified as the sealed run's id, a minor gap given the 0% coverage starting point.

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

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

Opens with a precise verb+resource+scope: 'Runs one read-only SQL statement over the parquet a run sealed, and waits for the answer.' This is clearly distinguishable from siblings like query_table (arbitrary tables) and get_artifact_download (bulk retrieval), and the read-only/single-statement limits are stated up front.

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 when: 'THIS IS HOW YOU CHECK THE DATA IS RIGHT before promoting anything: count the rows, look at the range, find the nulls,' which ties it to the promote_table workflow. It also routes the agent away from paging to get_artifact_download, and explains the timeout/query_id reuse path so a second statement isn't run.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is already known. The description adds substantial behavioral context beyond annotations: pagination via next_cursor, immutable version semantics, ceilings on columns/filters/sort keys/aggregates/group keys/rows, grouped aggregate behavior, the meaning of execution.truncated, and the requirement for an mr_use_ workspace key or OAuth connection. It also discloses that the first query connects the dataset to the workspace, which is a side effect not implied by the read-only annotation. No contradiction with annotations.

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

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

The description is dense but well-organized, with the core purpose front-loaded and examples embedded for clarity. Every sentence adds information, and the structure flows from basic query shape to operators to grouped aggregates to auth and alternatives. It is long, but the tool is complex with 9 parameters and many constraints; the length is justified. It loses one point because the density makes it harder to parse quickly, and some details (like the exact JSON example) could be trimmed without losing essential meaning.

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

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

For a tool with 9 parameters, no output schema, and no schema description coverage, the description is remarkably complete. It covers the query shape, all operators, pagination, grouping, aggregation, naming constraints, auth requirements, side effects, and the alternative for whole-table downloads. It even tells the agent to cite table.version_id and table.content_digest in responses. There is no output schema, so the description's explanation of return values (rows plus version_id and content_digest, next_cursor, execution.truncated) is essential and present.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It explains table_id, columns, filters (with all operators and their value requirements), order_by, limit, cursor, group_by, and aggregates (with aliases and naming rules). It provides two concrete JSON examples that illustrate how the parameters compose. It also explains edge cases like limit counting groups, offset and cursor being refused beside aggregates, and the behavior of aggregate queries without group_by. This far exceeds what the schema alone provides.

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

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

The description opens with a precise verb and resource: 'A bounded, structured query over one table's current version.' It immediately distinguishes itself from siblings like query_run, sample_rows, and get_table by stating it is a structured, non-SQL query over a single table's current version. The title 'Query a connected table' is reinforced with concrete detail about what the tool does and does not do (NO SQL).

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

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

The description explicitly states when to use this tool versus alternatives: 'For the whole table in one request, download the Parquet instead.' It also mentions connect_dataset as an explicit alternative for connecting a dataset, and clarifies that the first query over a dataset connects it to the workspace. The description gives clear context on when to use this tool (bounded structured queries) and when not to (whole-table downloads).

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

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

Goes well beyond annotations. Discloses that the server canonicalizes the document and computes the digest (so the user must not provide one), explains idempotency (identical bytes register once), notes error behavior (recipe_invalid with pointers), and clarifies source counting semantics (one id per source, not per page). Also states it builds nothing and costs nothing. All critical behavioral details are provided.

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?

Every sentence earns its place. The description is front-loaded with the core purpose, then adds essential behavioral details, examples, and next steps without fluff. Length is justified by the tool's complexity; it is efficient and well-organized.

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

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

For a single-parameter tool with no output schema, the description fully covers what an agent needs: the parameter's purpose, the return values (explicitly listed), error handling, idempotency, prerequisites (reading resources), and the next step. Nothing critical is missing.

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

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

Schema coverage is 0%, so the description must compensate. It explains the recipe parameter's role (defines data origin, shape, constraints) and gives an example placeholder. It directs users to resources for the exact structure rather than detailing it inline, which is acceptable for a complex document. The key constraints (no digest, one source id per source) are covered.

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 ('Registers') and resource (JSON recipe) and explains what the recipe defines (data source, shape, constraints). Clearly distinct from all sibling tools; no ambiguity about what it does.

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

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

Provides clear context: read reference resources before writing, and chains to start_run afterward. Doesn't mention alternatives because none exist for registering recipes, but it implicitly tells when to use it (when you have a recipe to register). No exclusions, but the guidance is practical.

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

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

Annotations only declare the safety profile (non-readOnly, idempotent, non-destructive, closed-world); the description adds the substantive behavior: no upstream acquisition, replay-enablement requirement, retention requirement, that replay never becomes live, and that approval must happen through the dashboard_url in a signed-in browser rather than via this 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-loads what the tool does and the no-upstream-acquisition fact, then covers preconditions and the return shape in a compact block. The closing sentence about approve_full_run and PREVIEW holds is a slight digression but earns its place as sibling routing.

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 helpfully enumerates the return shape ({run_id, status, mode, version, dashboard_url}) and covers prerequisites and the non-live/non-approving nature of replay. The only meaningful gap is the absence of any parameter-level semantics for three undocumented required inputs.

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

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

Schema description coverage is 0% and none of the three required parameters (recipe_id, recipe_digest, sources_from_run) is explained in the description. The phrase 'a named successful run of the same table' loosely maps to sources_from_run, but the recipe_id/recipe_digest pair is left entirely undefined, so the description fails to compensate for the coverage gap.

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

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

States a specific verb (Runs) and resource (a registered recipe revision) against a precisely scoped input source (retained raw inputs of a named successful run of the same table). The clause 'No upstream acquisition is performed' implicitly separates it from start_run, so an agent can distinguish it from siblings without opening their schemas.

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

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

Gives explicit preconditions ('Replay must be enabled and the inputs must still be retained') and steers the agent away from a wrong action ('Replay never becomes live and does not approve a repair', with approve_full_run handling a different hold type). It stops short of naming the tool to use when replay is not enabled or inputs are gone.

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 read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds valuable behavioral detail beyond annotations: bytes are never streamed through the server, partial output from failed runs is included, and the response shape is previewed. It does not contradict any annotation.

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

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

The description is compact and front-loaded with the artifact types, followed by run-state behavior, an example, return shape, and next-step guidance. Every sentence adds functional value, and there is no filler or repetition of schema details.

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

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

For a one-parameter read-only tool with no output schema, the description covers the run-state edge case, response fields, a concrete example, and the next tool to use. The only minor gap is that the 'more' field in the return shape is not explained, leaving pagination semantics slightly ambiguous.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining that run_id can reference running, succeeded, or failed runs, and gives a concrete example of the expected JSON shape. The UUID format is already strongly constrained by the schema, so the description only needs to contextualize the single 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?

The description states a specific verb and resource: lists the files a run sealed (parquet, profile, receipt, preview). It clearly distinguishes itself from get_artifact_download by noting that bytes are not streamed here, and it is distinct from get_run/list_runs in that it returns artifact metadata rather than run status.

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 covers valid run states: running, succeeded, or failed, including partial output on failure. It also provides an alternative, telling the agent to use get_artifact_download next if actual bytes are needed, which is clear when-to-use versus when-to-use-another-tool 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 declare read-only/idempotent/non-destructive behavior; the description adds non-blocking wait semantics, the 20s/100 caps, terminal flag meaning, and pagination via next_from_seq. No contradiction with annotations.

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

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

Every element earns its place: behavior is front-loaded, followed by the example, return shape, caps, and termination semantics. There is no fluff, tautology, or repetition of the title.

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

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

For a read-only tool with no output schema, the description covers input semantics, return fields, continuation, caps, and terminal behavior. An agent has what it needs to select and call the tool correctly.

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

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

Schema coverage is 0%, so the description carries the burden. It compensates by explaining from_seq as a continuation token, max_events and wait_seconds as stop conditions, their caps, and an example mapping all four parameters. It does not state defaults when optional parameters are omitted, leaving a minor gap.

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

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

Description opens with a specific action ('Opens the run's event stream'), names the resource (run event log), and defines its output behavior. The title and phrase 'watch a build without polling' clearly distinguish it from status/query/get tools.

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

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

Explicitly frames the tool as the way to watch a build without polling and explains the continuation pattern ('Call it again with from_seq set to next_from_seq'). It does not name sibling alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds meaningful context beyond those: no account needed, no query cost, same rows every time, default/max limits, and the distinction between row_count and total_row_count. No contradictions with annotations.

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

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

The description is front-loaded with the core concept, then covers constraints, an example, return shape, and the routing alternative in a compact, organized way. Every sentence earns its place and there is no filler.

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

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

For a simple two-parameter, read-only tool, the description is complete: it explains what the sample contains, how many rows, how to invoke it, what is returned, what total_row_count means, and how to go beyond the sample. The absence of an output schema is fully compensated by the explicit return-field list.

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

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

Schema description coverage is 0%, so the description carries the burden. It provides a concrete usage example for table_id and limit, states the default and maximum for limit, and explains the return fields. It largely repeats schema constraints for limit, but the example and return-field context compensate for missing schema descriptions.

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

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

The description states a specific verb, resource, and scope: it samples rows from a public table, emphasizing it is a materialized preview and 'NOT a query'. It clearly distinguishes itself from the sibling query_table, so an agent can tell them apart without opening schemas.

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

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

The tool explicitly says when to use it — for understanding shape and values — and gives an explicit when-not: 'To filter, sort, aggregate or read beyond the sample, use query_table, which needs a workspace key.' This names the alternative and the condition that selects 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behaviorally useful context beyond the annotations: the 20-match cap, no-account-needed requirement, canonical URL semantics, and that the search covers every public dataset. This exceeds the baseline expected when annotations are present.

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?

Every sentence earns its place: the first states the action and output, the second covers authentication and gives an example, and the third explains downstream chaining and sibling differentiation. The most important information is front-loaded and there is no filler.

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

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

For a simple one-parameter search tool with no output schema, the description fully specifies the return format, the limit, the auth expectation, the id/url semantics, the linkage to fetch, and the alternative sibling tool. There is no critical missing information that would prevent an agent from calling 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?

The schema has 0% description coverage, so the description must compensate. It provides a concrete example query ('hourly airport weather observations') and the expected overall request shape, which makes the single string parameter's purpose clear. It doesn't elaborate on edge cases such as empty results or term handling, but for a single free-text query the compensation is strong.

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

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

The description names a specific verb and resource ('Search every public dataset on Mostly Right'), states the exact return shape ({results: [{id, title, url}]}), and explicitly distinguishes itself from the sibling search_datasets. An agent can immediately tell what this tool does and how it differs from the richer paged variant.

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 positions this as the 'plain search-and-fetch pair' versus 'search_datasets [as] the richer, paged version with topics, publishers and summaries,' giving a clear selection criterion. It also tells the agent to pass a result's id to fetch for the full dataset document, which is concrete downstream usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds concrete behavior beyond that: the exact return structure, pagination semantics (next_cursor, null meaning), the critical clarification that publisher is the account that published here (not the original data source), and that omitting query lists recent datasets. It does not mention rate limits or potential performance, but for a read-only search that's acceptable.

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

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

The description is concise yet information-dense, covering purpose, usage, examples, return format, pagination, and follow-up steps in three sentences. It is front-loaded with the action and example, then fills in edge cases and clarifications. Every sentence earns its place; no fluff.

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 there is no output schema, the description must detail return values, which it does thoroughly (datasets array with fields, next_cursor). It also addresses pagination, the distinction between publisher and source, and follow-up actions. The tool is simple enough that the description covers all needed aspects for an agent to call it correctly.

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

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

The schema provides parameter names but no descriptions (coverage 0%), so the description carries the full burden. It explains `query` with an example, `limit` (implied by example but not explicit max, though schema gives that), `cursor` for pagination and how to use it (pass next_cursor back as cursor), and the effect of omitting `query`. It also clarifies that `topic` is available but not described; however, the core parameters are well explained. The description adds significant meaning beyond raw 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 it performs 'Full-text search over every public dataset on Mostly Right', which is specific about the verb and resource. It distinguishes itself from the sibling `search` (likely a general search) by its scope and from `get_dataset` by its search-and-list nature. The example invocation makes the purpose immediately concrete.

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

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

It explicitly says to 'Follow up with get_dataset(slug) for tables and schemas', which guides the agent to the next logical step. It also explains when to omit the query ('to list the most recently published datasets'), and the presence of siblings like `search` implies differentiation. The no-account-needed statement clarifies prerequisites.

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

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

Beyond annotations, the description discloses that the tool reads sources, can run for a long time, uses one progressive acquisition with an automatic inspection checkpoint after about five minutes, and can return status 'held' with projected_bytes and projected_runtime_seconds. This prevents the agent from misinterpreting the checkpoint as an approval gate or assuming immediate completion.

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

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

The description is long but dense with operational detail; every sentence contributes a distinct fact or guardrail, including a JSON example, return shape, and held-state behavior. It is front-loaded with the core purpose before adding workflow instructions.

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, no-output-schema tool with only sparse annotations, the description covers invocation modes, constraints, return fields, held behavior, and next-step tools. The main omission is resource_class semantics, and window format is left to the schema, so it is highly complete but not exhaustive.

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

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

With 0% schema description coverage, the description compensates by explaining the mode enum, requiring a ceiling for sample mode and a window for backfill mode, and showing an example with recipe_id, recipe_digest, and mode. However, resource_class is not explained, and the exact format of window start/end is left to the schema, so not all seven parameters are fully covered.

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

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

Description opens with 'Runs a registered recipe' and reinforces 'THIS IS THE TOOL THAT DOES THE REAL WORK', giving a specific verb and resource. It also distinguishes start_run from confirm_run and cancel_run by clarifying the run lifecycle and that the checkpoint is not an approval gate.

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 prescribes 'Start builds in full mode' and defines all four modes with field-level constraints: a sample needs at least one ceiling and a backfill needs a window. It also gives the post-call workflow ('Next: run_events... then query_run') and conditionally routes to confirm_run only when a held run's projections are accepted.

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. The description adds value beyond these by stating it 'does not write a recipe' and 'never retries preparation', clarifying the non-mutating one-shot behavior. It also discloses that it returns 'limits' which is useful context. No contradiction.

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 two sentences with no redundant phrasing. The main action is front-loaded, followed by return values, exclusions, and fallback guidance. Every sentence earns its place.

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

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

With no output schema, the description appropriately lists the returned identifiers and limits. It also clarifies what it does NOT do (write a recipe) and directs to the correct sibling in case of uncertainty. The only missing piece is parameter-level semantics, but the schema fully documents those, so the balance is adequate for an agent to call the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the three required parameters (dataset_id, question, source). However, it only mentions 'HTTPS source' which merely repeats the schema's URL pattern. It provides no additional meaning for dataset_id or question, and does not explain the nested rights_claim structure. The description adds negligible value over the schema for parameter understanding.

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 specific verbs ('Prepares', 'opens', 'queues') and identifies the resource ('HTTPS source'), clearly distinguishing it from the sibling get_source_inspection by naming it directly. The purpose is unambiguous even without reading 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 tells the agent when to use the alternative: 'If uncertain, preserve the coordinates and call get_source_inspection'. It also states a behavioral constraint ('never retries preparation'), giving clear guidance on when NOT to retry. This is a fully explicit usage clause.

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

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

Adds substantial behavior beyond the annotations: optimistic concurrency via version precondition (a concurrent change is refused rather than overwritten), workspace uniqueness on name, 'nothing rebuilds — metadata only', and the public-projection retry path. These are exactly the mutation semantics an agent needs and the annotations (readOnlyHint=false, idempotentHint=true) 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?

Information-dense but poorly front-loaded: the definition opens with the metadata-generation rules and buries the core 'changes a dataset's display name, its description, or both' in the middle. The metadata paragraph is also syntactically convoluted, forcing a re-read, though few sentences are truly 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?

Despite no output schema, it enumerates the return shape ({dataset_id, name, description, version, dashboard_url}) and covers name collisions, concurrency, sync fallback, and metadata-only scope. An agent has everything required to call it correctly across scenarios.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: it defines name semantics (working title vs. explicitly chosen, persistence rules), sync_only's retry-only role, and description semantics including that the opening paragraph becomes the search snippet and answer-engine summary, with a full worked example. This far exceeds what the bare schema provides.

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

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

States an unambiguous verb+resource ('Changes a dataset's display name, its description, or both') and differentiates from the sibling create_dataset by explaining that the name chosen at creation is only a working title. An agent can distinguish this from create_dataset and get_dataset 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 concrete invocation conditions: send name alongside the description to pin a title, and retry with {dataset_id, sync_only: true} when public_projection_synced is false. It also clarifies that drafts/unchanged descriptions generate no metadata. It stops short of explicitly routing among the many sibling update/list tools, but the 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?

The annotations already carry the write/destructive/idempotent hints, and the description adds useful behavior beyond them: append-only semantics, in-place revision when cell_id is reused, the return contract {cell_id, sequence}, and 'costs nothing and builds nothing.' The idempotent hint is clarified by the cell_id revision path rather than contradicted.

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

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

The description is compact and front-loaded, with every sentence contributing either behavior, usage, constraints, or the return value. The example JSON is directly actionable and earns its place.

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

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

For a 9-parameter tool with no output schema, the description covers the essential ground: purpose, when to use it, constraints, behavior, side effects, and return value. The remaining gap is the lack of explanation for several optional parameters, but the core decision-recording use case is fully specified.

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

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

With 0% schema description coverage, the description partially compensates by explaining the exactly-one run_id/dataset_id constraint, the meaning of cell_id, and by giving an example covering heading, markdown, and phase. However, blocks, revision_of, and checkpoint_seq are never described, and the required parameters are only implied by the example rather than stated.

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

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

The description opens with a specific verb and resource: 'Appends one cell to a run's or a dataset's decision record.' It goes on to specify what content belongs in the note and how it relates to the record, making the tool's purpose unmistakable and distinct from the surrounding get/list/run tools.

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

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

It tells the agent when to use the tool ('Write one for every decision worth explaining') and states an important precondition ('Exactly one of run_id or dataset_id'). It does not name explicit alternatives or when-not-to-use cases, but there is no obvious sibling that fills this role.

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