Mostly Right

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

It discloses important behavioral outcomes beyond the annotations: a run cancelled at the gate was never charged, the call returns a run receipt with status cancelled, and a finished run cannot be cancelled and reports that. This is meaningful behavior info beyond the schema, though it doesn’t discuss expected_version or other side effects.

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

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

The description is short and impactful: it leads with the main verb and scope, gives an example, and includes the critical failure/error path in a single extra sentence. Every part serves the ones or in doing so.

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?

It covers the main cancel action, the refund-relevant at-gate behavior, and the finished-run error path, but it omits any explanation of expected_version and does not provide an output schema or return-fields breakdown. Given zero parameter coverage and no output schema, the description is helpful but not fully self-sufficient.

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

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

The description only gives a raw example of run_id and does not explain the semantics of expected_version at all. Since schema description coverage is 0%, the description should carry the explanatory burden for both parameters; it does almost nothing to add meaning beyond the JSON structure.

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?

It states a specific action (Stops a run), the exact resource, and the lifecycle states it applies to (queued, held at spend gate, running). It also contrasts with get_run in the last sentence, distinguishing the cancel operation from the read operation.

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 the tool (queued, held at the spend gate, running) and when not to (already finished runs), and it names the action to take instead (read get_run rather than retrying). That gives the agent direct guidance for handling the primary error case.

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?

The description discloses that the tool mutates state (starts the run), returns a receipt with new status, and enforces optimistic concurrency via expected_version. It adds meaningful behavior beyond annotations (idempotentHint, readOnlyHint=false) by explaining the locking mechanism and the refusal condition.

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 sentences, no filler. The purpose is front-loaded, the concurrency behavior is explained in the middle, and the usage condition closes it. Every sentence adds value, including the example which is compact and illustrative.

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 two parameters and no output schema, the description covers the purpose, the precondition for use, the critical parameter semantics, and the return value. It is complete enough for an agent to know when and how to invoke it correctly.

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

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

Schema coverage is 0%, so the description carries the burden. It explains expected_version's purpose and usage with an example, and run_id is self-evident as a UUID. However, run_id is not explicitly described, though its role is obvious from context. The example clarifies the JSON shape.

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

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

The description clearly states a specific action: 'Authorizes the spend a held run was projected at, and starts it.' It identifies the resource (a held run) and the outcome (starting it), and it is distinct from siblings like start_run and cancel_run by the authorization precondition.

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 guidance is given: 'Only call this after a person has seen the projected cost and agreed to it.' It also instructs to pass expected_version from get_run to prevent stale authorization, which is a concrete usage rule. Though it doesn't name alternative tools, the condition is unambiguous.

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?

Beyond the annotations, the description adds that the call is safe and non-destructive ('Costs nothing to run and builds nothing'), that the created object is empty, and that dataset_id is the value consumed by downstream build tools. This adds meaningful behavioral context without contradicting the readOnlyHint, idempotentHint, or destructiveHint values.

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

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

The description is front-loaded with the core action and return value, then adds domain context, an example, and a clear next step. Some lifecycle prose is slightly discursive, but each sentence contributes to an agent's understanding of when and how to use the tool.

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

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

For a low-complexity create tool with two simple parameters and no output schema, the description covers inputs, return shape, identifier roles, side-effect/cost profile, and the next step in the build flow. An agent has enough information to call it successfully and interpret the returned ids.

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 example payload is valuable and shows realistic values for both name and description. It also explains the role of the returned identifiers (dataset_id vs cloud_dataset_id), though it does not explicitly discuss optionality, uniqueness, or formatting rules beyond what the schema already encodes.

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

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

The opening sentence names the exact verb ('Creates'), the object ('an empty dataset'), the scope ('in your workspace'), and the result ('returns its ids'), making the tool's function immediately identifiable. It also clarifies what a dataset is in this domain ('container a recipe binds to'), distinguishing creation from recipe/run tools such as register_recipe or start_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 provides clear workflow context: the dataset is an empty container that exists before a recipe or rows, and it ends with an explicit next step ('write a recipe and call register_recipe with this dataset_id'). It does not, however, name alternatives such as update_dataset or list_my_datasets, nor give conditions for when not to use the tool.

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

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

Annotations 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 carry readOnlyHint=true and idempotent/read-safe traitsnis, and the description adds meaningful behavioral context beyond safety: it reports build state rather than published state, includes held runs awaiting spend confirmation, and scopes results to the caller's workspace. 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 compact and front-loaded: scope first, then response shape, then use case. The example and the explicit return fields duplicate some information but still serve the agent by making the data shape concrete without excessive prose.

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 read-only tool with no output schema, the description is complete: it lists the full return shape, explains the 'build terms' distinction, identifies the appropriate call timing, and disambiguates from the sibling public get_dataset. An agent has enough context to invoke this 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 single dataset_id parameter is already well-specified by the schema (type, format, pattern). The description adds only mild semantic context—that the dataset is 'my' workspace dataset and a placeholder example—but does not explain where to obtain the ID or how it interacts with the result. It is adequate but not rich.

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 scope: it retrieves 'one workspace dataset in build terms' and enumerates exactly what is included (each table's build state, promotion state, live version, latest run, held run). It also distinguishes itself from the sibling get_dataset, so the agent knows this is the workspace-private variant, not the public one.

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 'This is the tool to call after a run finishes to see what it produced' and contrasts itself with 'public get_dataset, which reads the published catalog.' This gives the agent both a positive trigger and a clear alternative to rule out.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description goes well beyond that by explaining null-field behavior before delivery, the 'unchanged' outcome, when the pages object appears, that budget_exhausted indicates intentional partial coverage, and that the tool is cheap. No contradictions with annotations exist.

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 every sentence earns its place: it covers return fields, null semantics, truncation handling, the pages object, failure interpretation, cost, and sibling routing. Important guidance is front-loaded, and the density is appropriate for the tool's complexity.

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

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

For a simple one-parameter read tool with no output schema, the description is exceptionally complete. It documents not just what is returned but the meaning of nuanced states like 'unchanged', 'truncated', and 'pages.complete false', plus the version number needed for confirm/cancel. Nothing an agent needs to correctly invoke and interpret this tool is missing.

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

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

There is only one required parameter, run_id, and the description includes an example placeholder but does not explicitly explain the meaning of run_id or where to obtain it. The input schema itself provides type, format, and pattern, so the parameter is largely self-explanatory, but the description does not add meaningful semantic value beyond that.

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

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

The description opens with 'One run's current state' and then enumerates exactly what is returned: status, mode, clamps, rows, truncated, table/table version, failure details, and version number. It clearly identifies the resource (a single run) and the action (get/read), and it differentiates itself from run_events by specifying this is for a single status check rather than watching an ongoing 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 usage direction: 'Prefer run_events when you want to watch a run that is still going; use this for a single status check.' It also tells the agent to 'ALWAYS read truncated before treating a sample as complete' and warns not to interpret pages.complete false as a failure. These are clear, actionable when-to-use and interpretation rules.

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

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

With readOnlyHint, idempotentHint, and destructiveHint already provided by annotations, the description adds value by specifying exactly which state fields are returned, including the platform's learned rhythm and failure reasons. This gives the agent expectations for the response without violating existing hints.

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: two sentences plus a field list and example. The core purpose is front-loaded, the return format is presented clearly, and every sentence serves a purpose – 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?

With only one parameter, no output schema, and full annotations for safety, this is sufficient to call the tool correctly. The description names the expected return fields, so the agent knows exactly what it will receive. Even the source of the input is covered.

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 explicitly states where valid table_ids come from and provides a JSON example. This supplies meaning beyond the bare uuid type, compensating for the schema gap.

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

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

The description states a precise verb and resource: 'One table as the builder sees it' and enumerates the specific state fields it returns (promotion, live version, refresh schedule, rhythm, last refresh, failure). This immediately distinguishes it from siblings like get_table_schema (schema) and list_tables (list), so an agent can route the call correctly.

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

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

The description gives a clear context and even advises where table_id values come from ('register_recipe, get_my_dataset or a run receipt'), which is practical input guidance. It does not explicitly list alternatives or exclusions, but the distinct set of returned fields makes it obvious when this tool is appropriate.

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?

The description reveals many non-obvious behaviors: the tool refuses without confirm:true, starts a recurring refresh, returns held_run projections if spend crosses a threshold, and still promotes the table in that case. This goes far 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 dense but every sentence earns its place: main effect, example, consent requirement, precheck, return shape, and edge-case follow-up. It is well organized and front-loads the essential nature of the tool.

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

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

For a mutating promotion tool with no output schema, this description covers scenario, human approval, prerequisite check, return values, side effects, and follow-up actions. The only minor gap is cadence parameter details, but overall it is exceptionally 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?

With 0% schema description coverage, the description compensates well for confirm and table_id, including an example and the rule that confirm must be true. Cadence is only indirectly connected to the recurring refresh and return field, so its semantics are slightly underspecified.

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

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

The description states the specific action: promoting a table's newest passing version to the version everyone reads. It clearly identifies this as the one human gate, making it easy to distinguish from sibling tools like start_run, confirm_run, and cancel_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?

It explicitly says to call only when the person the agent is working for has approved it, to check data with query_run first, and to not call start_run for this promotion. It also explains when to follow up with confirm_run or cancel_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 cover read-only/idempotent/non-destructive, and the description adds a great deal: allowed statement prefixes, max_rows cap, 16 KiB trimming, wait/timeout behavior, and query_id reuse. The only blemish is mentioning 'rows_omitted' while the listed return shape says 'truncated', which slightly muddies the behavioral contract.

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 each sentence is functional: purpose, use case, example, constraints, return shape, size limits, and retry behavior. There is no filler, and the most important scoping information is front-loaded.

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 supplies the return fields and the key timeout/truncation behaviors. However, it does not explain all return field semantics such as possible state values or what result_digest represents. Still, it provides enough to invoke the tool and handle the main outcomes.

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 parameter burden. It explains run_id, sql restrictions, max_rows cap, query_id reuse on timeout, and wait_seconds cap, plus gives a complete example call. This fully compensates for the empty 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 and resource: 'Runs one read-only SQL statement over the parquet a run sealed' and immediately gives a concrete use case ('check the data is right before promoting anything'). It is clearly distinguishable from siblings like query_table and get_artifact_download.

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 when to use this tool, including examples (count rows, look at the range, find nulls), and tells when not to use it by directing large/wide cases to aggregation or get_artifact_download. It also explains the timeout/resubmission workflow with query_id.

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

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

Annotations only say readOnly/idempotent/non-destructive; the description adds the real behavioral payload: auth requirements (mr_use_ key or OAuth), the immutable-version snapshot semantics, cursor pagination protocol, ceilings on columns/filters/sorts/aggregates/rows/bytes, and the citation fields returned. This is far beyond what annotations provide.

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

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

Front-loads the key constraint (NO SQL, bounded structured query), then example, then ceilings, then pagination and auth. Dense but every sentence is load-bearing; slightly long but no filler.

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

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

With 8 params, no output schema, and 0% schema coverage, the description supplies the missing pieces: auth, pagination lifecycle, hard limits, return fields, and the alternative path. An agent has everything needed to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it enumerates the operator set, shows a concrete JSON example, and documents the cursor round-trip. It leaves some gaps on offset behavior and the aggregates object shape, but the semantics for the main fields are well 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 precise verb+resource: a bounded, structured query over one table's current version. Distinguishes from siblings by explicitly ruling out SQL and by pointing to download-the-Parquet for the whole table and connect_dataset for explicit connection.

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 NO SQL and what to send instead, names the alternative (Parquet download) for whole-table reads, and explains the first-query-connects behavior with connect_dataset as the explicit alternative. Covers when to use and when to use something else.

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 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?

The description goes well beyond the annotations. It warns that this is the tool that spends money, explains the held status with projected_bytes/projected_runtime_seconds/projected_cost, and clarifies that a sample must state a ceiling. The annotations already declare idempotentHint=true and destructiveHint=false, and the description does not contradict them; it adds the cost and hold behavior that annotations cannot express.

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

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

The description is dense but every sentence earns its place: the cost warning is front-loaded, the mode definitions are compact, the example is illustrative, and the follow-up tool routing is at the end. It packs a lot of critical information into a few sentences without 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 7-parameter tool with no output schema, the description is remarkably complete. It covers the return shape (run_id, status, mode, version, dashboard_url), the held status behavior, the mode-specific constraints, and the next steps in the workflow. The only minor gap is the lack of explicit mention of resource_class, but the description still provides enough for an agent to call the tool correctly in the common paths.

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 explains the meaning of mode (four values with one-line definitions), the window object (start/end), and the ceiling parameters (max_rows, max_source_bytes, window) in the context of sample and backfill. It does not explain resource_class or recipe_digest, but the example and the mode semantics cover the most decision-critical parameters. Given the 0% coverage, this is strong compensation, though 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?

The description opens with a specific verb and resource ('Runs a registered recipe') and immediately distinguishes the four modes (sample, full, refresh, backfill) with one-line definitions. It also names the sibling tools it is not (confirm_run, run_events, query_run), so an agent can tell it apart from the surrounding run lifecycle tools 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?

The description gives explicit when-to-use guidance: 'always start here' for sample mode, and it states the exact conditions for sample and backfill (sample must state a ceiling; backfill must state a window). It also tells the agent what to do when a run is held (show projected costs and call confirm_run only if the user agrees), and it names the next tools to use (run_events, query_run). This is exemplary routing and 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?

The description discloses the optimistic concurrency behavior (reads current version and refuses concurrent changes) and the side-effect-free nature ('metadata only'), which are not captured in the annotations. The annotations only state idempotentHint=true and destructiveHint=false, but the description adds critical behavioral details about precondition handling and that no rebuild occurs. 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 a single focused paragraph that front-loads the purpose, then provides an example, return format, and key constraints. Every sentence contributes value: the concurrency note, the metadata-only clarification, and the uniqueness rule are all essential. There is no fluff 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 3-parameter tool with no output schema, the description covers everything an agent needs: the action, the exact parameters via example, the return object, the concurrency behavior, the uniqueness constraint, and the side-effect-free nature. The absence of an output schema is compensated by the explicit return format. Nothing critical 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 coverage is 0%, so the description must compensate. It clarifies that 'name' and 'description' are the editable fields and that 'dataset_id' identifies the dataset. The example provides a concrete usage, and the uniqueness constraint on 'name' adds semantic meaning beyond the schema's simple string type. While it doesn't detail every parameter's format, the schema already provides type and length constraints, and the description covers purpose.

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 ('Changes') with a clear resource ('a dataset's display name, its description, or both'). It explicitly distinguishes this as a metadata-only update, which separates it from sibling tools like create_dataset or query_table. 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?

The description provides clear context for when to use this tool: it is for metadata updates only, explicitly noting 'Nothing rebuilds.' It also implies it applies to existing datasets and mentions the uniqueness constraint on names. However, it does not explicitly name alternative tools for other operations, though the metadata-only boundary is a strong usage guideline.

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.