rows.page

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

With no annotations, the description carries the full behavioral burden. It does usefully disclose the immediate effect ("Its URL stops working immediately"), which hints at irreversibility, but it never states whether the deletion can be undone, what auth is required, or whether the change is permanent/async.

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

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

Two short sentences, zero filler, with the core action front-loaded and the side effect following immediately. Every clause earns its place.

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

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

For a two-parameter tool with no output schema, the description covers the action, the ownership precondition, and the observable effect. The main omission is an explicit statement that the deletion is irreversible and any auth requirement, but the essentials are present.

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

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

Schema description coverage is 100% with only two parameters, so the schema already documents both 'dataset' and 'token'. The description adds no parameter-level detail, meaning the baseline of 3 applies.

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

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

"Delete a dataset you own" pairs a specific verb with a specific resource and adds an ownership scope. It is unambiguously distinct from the read-oriented siblings (get_dataset, list_datasets), though it never names them or states the alternative to use instead.

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

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

There is no when-to-use or when-not-to-use guidance, no mention of prerequisites such as required permissions or confirmation, and no reference to any sibling tool. The only contextual cue is the ownership qualifier "you own," which is a constraint rather than usage direction.

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?

No annotations exist, so the description carries the full burden. It does disclose useful behavior: the response is bounded to the first 20 preview rows, and "Read" implies a non-mutating operation. It does not mention authentication expectations for private datasets, pagination, or error behavior, which are left to the schema's token description.

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

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

A single sentence that front-loads the action and then lists the returned components in priority order. Every clause carries information; nothing is 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?

With no output schema, the description usefully compensates by enumerating the return contents, including the preview row cap. For a low-complexity read tool with three fully described parameters, this is nearly sufficient, though it omits any note about permissions or large-dataset behavior.

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

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

Schema description coverage is 100%, so token, dataset, and version are already documented in the schema. The description adds no parameter-level detail (e.g., what version omits to by default), so the baseline of 3 applies.

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

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

The description pairs a specific verb ("Read") with a resource ("a dataset") and enumerates the payload it returns: meta, versions, findings, columns, and a 20-row preview. This implicitly separates it from list_datasets and delete_dataset, but it never names or contrasts a sibling explicitly.

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

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

There is no statement of when to reach for this tool versus list_datasets or get_limits, and no prerequisites or exclusions are given. An agent can infer it fetches one dataset's details, but the description offers no routing guidance at all.

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

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

With no annotations, the description carries the full burden. 'Show' implies a side-effect-free read and it usefully enumerates the returned contents (caps plus usage), which matters since there is no output schema. It stops short of stating read-only behavior explicitly or any permission/scope requirements.

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

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

One sentence, front-loaded with the action and packed with the specific items returned. No filler, no restatement of the tool name.

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 informational tool with no output schema, the description adequately signals the shape of the result by naming the caps and usage. It would be fully complete if it said who can call it or when in a workflow it is useful.

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

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

The tool takes zero parameters, so per the rubric baseline is 4. There is nothing for the description to clarify beyond confirming no input is required, which the empty schema already conveys.

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?

Specific verb ('Show') plus a precisely enumerated resource: the plan, its caps (file size, datasets, version history) and current usage. No sibling (delete_dataset, get_dataset, list_datasets, pin_finding, push) operates on plan limits, so the agent can place it unambiguously.

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 says what is returned but never says when to reach for this tool — e.g. before pushing large datasets or when diagnosing a cap error — nor does it reference any alternative. Usage is left entirely to inference from the sibling list.

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 no annotations, the description carries the full burden. It usefully discloses the auth requirement and the sort order ('newest first'), which an agent cannot get from the schema, but it says nothing about pagination behavior despite the tool being cursor-paginated, nor about result size or rate limits.

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

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

Two short sentences, no waste, and the core purpose is front-loaded ahead of the auth caveat.

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 list tool with no output schema, the description covers scope, ordering, and auth. The only real omission is any mention of pagination, which matters because a cursor parameter exists.

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

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

Schema description coverage is 100% (the single cursor parameter is documented as 'next_cursor from the previous page'), so the parameter is already explained. The description adds nothing about the cursor or paging, which is the baseline 3 case.

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

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

States a specific verb and resource ('List the datasets') plus the account scope and ordering ('newest first'), which naturally separates it from get_dataset (singular) and delete_dataset. It never names a sibling explicitly, so differentiation is inferred rather than stated.

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

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

The only usage-adjacent information is the prerequisite 'Needs an API key.' There is no guidance on when to use this versus get_dataset or the other siblings, and no condition that would route the agent elsewhere.

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?

No annotations are provided, so the description carries the full burden for this mutation tool. It discloses the ownership requirement, but says nothing about side effects, idempotency, whether it overwrites an existing finding of the same title, or what the operation returns on success. It also introduces a subtle ambiguity about how the 'sql' parameter relates to a 'q' that looks like SQL.

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

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

The purpose is correctly front-loaded, but the query-language syntax is delivered as one very long, unformatted sentence that is hard to scan. The content is high-value, yet a bulleted or clause-separated structure would carry the same information more efficiently.

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 ten-parameter mutation tool with no annotations and no output schema, the description is rich on filter syntax but thin on operation semantics. It leaves the agent unsure of the write's effect and return behavior, though the 100%-covered schema compensates for the parameter side.

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

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

Schema coverage is already 100%, which sets a baseline of 3, but the description adds substantial meaning beyond the terse schema descriptions: full query-language grammar for 'q' (ranges, ISO dates, dot paths, tags, OR/parentheses), SQL fallback against table `data`, and the comma/`-` syntax for 'sort' and 'cols'. It omits any commentary on note, token, version, or row_count, so it stops short of a 5.

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

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

The description states a specific verb and resource ('Pin a finding') and helpfully defines the term with the parenthetical '(a saved, titled view)'. That definition is the main thing preventing confusion with siblings like push. It does not, however, differentiate itself from those siblings or explain how a finding relates to a dataset push.

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 only usage context offered is the ownership constraint ('a dataset you own'), which functions as a prerequisite. There is no guidance on when to pin a finding versus using the sibling 'push', no exclusion conditions, and no note on whether re-pinning an existing title is expected.

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 no annotations, the description carries the full behavioral burden and does well: 16 MB inline limit, idempotency ('identical content returns unchanged: true'), re-push diff reporting (rows_delta, columns_added/removed, diff_url) and 7-day anonymous expiry. It omits explicit auth/permission requirements and rate-limit/error behavior, which keeps it from a 5.

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

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

It is front-loaded correctly, beginning with purpose and the exactly-one-input rule. However, the bulk of the text is a dense query-language reference appended to a publish tool, which reads as documentation better placed elsewhere and inflates the description considerably.

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 19-parameter, no-output-schema, no-annotation tool, it covers most of what an agent needs: input exclusivity, size limit, idempotency, diff output fields and expiry semantics. Remaining gaps (auth requirements, failure modes) are modest given the extensive behavior already disclosed.

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 95%, so the baseline is 3 and the schema already documents all 19 parameters. The description adds real value beyond the schema by spelling out the rows.page query-language grammar for q, and the sort/cols syntax. It stops short of 5 because those additions don't change how a caller fills the remaining scalar params.

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

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

The opening states a specific verb+resource+outcome: 'Publish rows as a rows.page dataset (or a new version of one) and get a shareable URL.' This lets an agent separate it from the read/list siblings. It never names a sibling alternative (e.g. get_dataset for retrieval), so it stops short of full differentiation.

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?

Rich within-tool guidance: 'Pass exactly one of csv, tsv, jsonl, json, rows or url' and 'use url for bigger files' tells the agent how to select inputs and when a format is preferred. It gives no explicit when-to-use-vs-alternative framing against delete_dataset/get_dataset, so it is context without exclusions.

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