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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the important side effect that existing rows are backfilled with the column's default value or null, and it documents both success and failure return shapes, including specific failure reasons such as duplicate columns and invalid enum definitions. It omits permission or reversibility details but covers the core mutation behavior well.

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: purpose, behavioral consequence, usage trigger, arguments, return values, and example. Every section earns its place, and the key facts are front-loaded rather than buried. There is no redundant or filler content.

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

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

For a two-parameter mutation tool with no annotations and an opaque column object schema, the description covers backfill behavior, success and error returns, failure triggers, and a runnable example. It is not fully self-contained because the complete column definition shape lives in create_dataset, but it gives enough pointers for an agent to proceed.

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 input schema has 0% description coverage, so the description must compensate. It meaningfully describes dataset as needing the exact name, and it explains that column uses the same shape as create_dataset, backed by an example. However, the full column definition is delegated to another tool rather than documented here, so agents still need cross-tool context to construct valid column objects.

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, 'Add a new typed column to an existing dataset', making both the resource and operation explicit. The use case 'start tracking something new in an existing dataset' and the concrete natural-language example further clarify its scope and distinguish it from sibling tools like update_column, remove_column, and create_dataset.

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

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

It gives a clear trigger condition: 'Use this when the user wants to start tracking something new in an existing dataset', including a sample user request. It does not explicitly name alternatives or say when not to use this tool, but the situational guidance is unambiguous enough for selection.

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 provided, the description carries the full disclosure burden. It does this well by explaining that invalid rows are rejected while valid rows are saved, that the call is limited to 100 rows, and that rejected rows are reported with plain-language reasons. It also provides the complete return shape, making side effects and failure behavior transparent.

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 organized into a clear summary, usage note, Args, Returns, and Example. Every section adds necessary information: the prerequisite check, the limit, the return contract, and a concrete example. There is no filler or redundancy that dilutes the guidance.

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

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

For a two-parameter tool with no annotations, the description is complete: it explains when to use it, how to prepare, what the inputs mean, what outputs look like, and how to handle rejected rows. The example further anchors the expected call shape. No critical operational detail 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 description coverage is 0%, so the description must fully compensate. It clearly explains that dataset is the exact dataset name with an example, and that rows is a list of row objects mapping column names to values with an inline example. It also adds the 100-row limit and validation behavior that the schema does not convey.

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: 'Add one or more rows to a dataset with per-row validation.' It clearly identifies the operation as adding rows and even differentiates its behavior from related tools by emphasizing validation and partial saves.

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

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

It gives clear usage context: use this to capture records the user dictates in conversation, check describe_dataset first to ensure columns and constraints match, and relay rejected rows. It does not explicitly enumerate when not to use it versus alternatives like import_rows or update_rows, so it misses the full explicit 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?

With no annotations, the description fully discloses behavior: it creates a new dataset, enforces case-insensitive uniqueness, defines column validation rules, and specifies both success and failure return formats. The example illustrates exact input/output structures.

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?

Organized with purpose, args, returns, and example. Every sentence adds value, and the example is illustrative. Length is justified by tool complexity; nothing is redundant.

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

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

Covers what the tool does, when to use it, required pre-call confirmation, parameter semantics, return values, and a realistic example. With no output schema, it still fully explains output structure and error handling.

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% (schema only lists names/types), but the description explains each parameter in depth, including column type list, per-type attributes, and constraints (e.g., enum requires at least one option). This vastly exceeds schema detail.

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 explicitly states the tool creates a new dataset (table) with typed columns and gives concrete use cases (candidates, inventory, payments). It clearly distinguishes from siblings like add_column, list_datasets, and delete_dataset.

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 direct guidance: 'Use this whenever the user wants to start tracking something new' and mandates a workflow ('Always propose the column list... get confirmation before calling'). This is unambiguous and actionable.

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 fully discloses destructive behavior, the confirm-gate mechanism, preview vs. actual deletion, and exact return formats. It highlights the irreversible nature and requires explicit confirmation, which is comprehensive for an agent.

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 logically structured: purpose, safety warning, parameters, returns, and example. Every section serves a purpose and is front-loaded with the critical safety note. 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?

Despite the lack of annotations and rich schema, the description covers all necessary context: safety, usage workflow, parameter semantics, return values, and a concrete example. An agent can call the tool correctly with only this description.

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 zero descriptions (0% coverage), but the description fully explains both parameters: 'name' as the exact dataset name and 'confirm' with its default and behavioral effect. An example ties it together, far exceeding what the schema alone offers.

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 ('Delete') and resource ('an entire dataset and all of its rows'), which clearly distinguishes it from sibling tools like delete_rows. The intent is unambiguous and directly actionable.

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 an explicit two-step workflow: first invoke with confirm=false to preview, then with confirm=true after user agreement. This tells the agent exactly when and how to use the tool, though it does not compare directly to delete_rows, the workflow is complete and self-contained.

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 disclosure burden and does so thoroughly. It labels the operation as destructive, explains the preview vs. actual deletion behavior, documents the confirm default, and specifies both return shapes. This is far beyond what the bare input schema conveys.

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 yet information-dense: purpose, safety workflow, args, return values, and example are clearly labeled and easy to parse. The destructive warning is front-loaded, and every sentence contributes to safe and correct invocation.

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

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

The description covers all needed context: how to preview, how to confirm, what arguments to pass, what responses to expect, and a concrete example. Despite having no annotations, an agent has everything necessary to invoke the tool safely and interpret its output.

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 fully compensates by providing a dataset example, row_ids example with mutual exclusivity, a structured conditions example, and confirm default semantics. Each parameter is given practical meaning beyond its raw type 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 starts with a specific verb and resource: 'Delete rows by explicit ids, or in bulk for every row matching a filter.' This clearly distinguishes it from siblings like delete_dataset, add_rows, and update_rows, and identifies the two supported deletion modes.

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 workflow guidance: call with confirm=false first, tell the user what will be lost, then re-invoke with confirm=true after agreement. It also clarifies that row_ids and conditions are mutually exclusive. It doesn't explicitly name alternative sibling tools for when not to use it, but the usage context is otherwise strong.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the return format on success and failure, the sample row cap of 5, the default of 0, and that it describes column definitions and row count. 'Show' implies a read-only operation, though it does not explicitly state that no data is modified.

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-structured with a front-loaded purpose sentence, followed by usage context, Args, Returns, and an Example. Every section earns its place, and the format makes key facts easy to scan.

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 annotations, the description is complete for a two-parameter introspection tool: it covers purpose, when to use it, parameter semantics, expected return shape, error behavior, and an example call. No critical operational detail 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 input schema has no property descriptions (0% coverage), so the description must fully explain parameters. It does: 'Exact dataset name, e.g. "Candidates"' adds precision, and 'Optional number of first rows to include, 0-5 (default 0)' clarifies range, default, and meaning beyond the bare 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 opens with a specific verb and resource: 'Show a dataset's full column definitions (types and constraints) and row count.' This clearly differentiates it from sibling tools like search_rows or get_row, which retrieve data rows rather than schema metadata.

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 states 'Use this before adding or searching rows so you know the exact column names, types, and constraints,' giving clear when-to-use guidance. It does not explicitly name alternatives or state when-not-to-use, but the intended context 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?

With no annotations provided, the description carries the full burden and does well: it reveals that the id column is always included, that existing files are not overwritten without overwrite=true, that format is inferred from the file extension unless forced, and what the return object looks like. This is meaningful behavior beyond the schema; only a few edge details like file-size limits or permission requirements are absent.

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 organized with a summary line, a usage note, a compact Args list, a Returns line, and a worked example. It is long only because there are six parameters to clarify, and every section adds useful information without repetition.

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 six-parameter export tool with no annotations and an output schema, the description is comprehensive: it covers filters, projection, format inference, overwrite safety, return shape, and includes an example. There is no missing information an agent would need 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 description coverage is 0%, but the description compensates fully by explaining every parameter, providing concrete examples for conditions and the overall call, and noting defaults for format and overwrite. An agent can construct a correct invocation from the description alone.

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 clear verb-resource-action statement: 'Export rows (optionally filtered and projected) to a CSV or JSON file.' This unambiguously distinguishes it from sibling read/search/write tools, and the 'spreadsheet-friendly form' phrasing reinforces the practical 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?

It explicitly says when to use the tool ('Use this when the user wants their data back in a spreadsheet-friendly form') and connects filtering to the search_rows syntax, which helps an agent reason about shared semantics. It does not explicitly contrast with search_rows or other alternatives, 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?

With no annotations, the description carries the behavioral burden. It discloses success and error return shapes, including what happens for unknown ids or columns, and the projection behavior. It does not explicitly state the operation is read-only, though 'Fetch' and the return contract make that reasonably clear.

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 purpose, then gives usage guidance, args, returns, and an example in a compact, organized format. Every section adds necessary information 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 three-parameter read tool with no annotations and no property descriptions in the schema, the description provides everything needed: purpose, when to use, parameter semantics, return contract, error behavior, and a concrete example. 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 description coverage is 0%, so the description must fully compensate, and it does. It explains dataset as an exact name, row_id with an example, and columns as an optional projection list, plus a complete call example. All three parameters are effectively documented.

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: 'Fetch a single row by id,' optionally limited to columns. It clearly distinguishes this tool from siblings like search_rows by emphasizing single-record retrieval, and includes concrete user-phrase examples.

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

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

It gives an explicit when-to-use condition with examples like 'show me row 12' and advises requesting only needed columns to keep responses small. However, it does not explicitly name when-not-to-use or point to search_rows for multi-record queries, so it stops short of full alternative 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?

With no annotations, the description carries the behavioral burden and does so well: it reveals that previews happen before commit, that rows are validated against the schema, that CSV values are coerced, and that invalid rows are reported. It stops short of explicitly stating whether the preview is fully non-mutating or whether the import is transactional.

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 section earns its place: purpose, two-step behavior, parameter definitions, return shapes, and an example. It is well-structured with clear headers and front-loaded with the core behavior.

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

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

For a complex two-phase tool with five parameters and no annotations, the description covers the full call contract: all parameters, both phase return shapes, defaults, validation behavior, and an example. Nothing essential for invoking it correctly is missing.

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

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

Schema description coverage is 0%, but the description compensates fully by explaining every parameter: dataset name, file path, format auto/csv/json, confirm gating the actual import, and create_if_missing behavior. The example reinforces how the parameters are used together.

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 a specific action ('Import rows into a dataset'), the source formats (CSV/JSON), and the two-step preview/commit model. This makes it easy to distinguish from file-export or manual-row tools, but it never explicitly names sibling tools or states what it is not.

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 clearly explains the intended workflow: call with confirm=false first, share the mapping with the user, then call with confirm=true to commit. It also explains create_if_missing behavior and defaults, but it does not explicitly compare against alternatives like add_rows or validate_rows.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly discloses pagination behavior, instructs the agent to use next_offset rather than raising the limit, and specifies the exact response shape. This goes well beyond a simple 'lists datasets' and gives the agent actionable behavior expectations.

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

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

The description is well-structured and front-loaded: a one-sentence purpose, a usage context line, then a compact Args/Returns/Example layout. Every section earns its place and the example is genuinely useful. No filler or redundant restatement.

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 list tool, this description is complete: it covers behavior, pagination, parameter semantics, and return shape, and even gives an example. The presence of an output schema means the described Returns section is a bonus, and the pagination warning covers a common mistake. Nothing essential 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 description coverage is 0%, so the description must fully compensate. It does: the Args section adds meaning beyond the schema by explaining limit as page size with a valid range (1-100), explaining offset as the number of datasets to skip, and restating defaults. This is exactly what an agent needs to call the tool correctly.

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

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

The description opens with a specific verb-resource pair: 'List all datasets' and adds the distinguishing detail of row counts and a name:type column summary. This sets it apart from siblings like search_rows, create_dataset, and describe_dataset, so an agent can tell what it does without inspecting the schema.

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

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

The description explicitly states when to use the tool: 'Use this to discover what the user is already tracking before creating or querying a dataset.' This is clear contextual guidance, though it does not explicitly name alternative tools or exclusion conditions, so it falls just 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the tool is destructive, that confirm defaults to false and produces only a preview, and it documents all three return shapes including the error case for unknown columns.

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

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

The description is front-loaded with the most important safety warning, then efficiently documents parameters, return values, and an example. Every section earns its place and nothing is redundant or vague.

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

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

For a destructive three-parameter tool with no annotations, the description is fully complete. It covers the safe workflow, required arguments, default behavior, return values, and an example invocation, leaving no critical gap 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?

Schema description coverage is 0%, so the description must explain parameters itself, and it does. It defines dataset as an exact name with an example, defines column as the column name to remove, and explains that confirm must be true to actually remove, contrasting with its default false.

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

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

The description states a specific verb and resource: 'Remove a column from a dataset,' and immediately distinguishes itself from related operations like add_column and update_column. The 'after explicit confirmation' qualifier further clarifies the tool's special destructive nature.

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 procedural guidance: call with confirm=false first, show the user what will be lost, and only re-invoke with confirm=true after agreement. This clearly tells the agent when and how to use the tool, including the safe alternative flow.

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 provided, the description carries the full burden of behavioral disclosure, and it delivers thoroughly. It explains pagination behavior ('page with next_offset instead of raising the limit'), fuzzy result ordering by similarity, the inclusion of _score in fuzzy mode, and that id is always included in column projection. These details go far beyond the schema and give the agent a precise model of the tool's runtime behavior.

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

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

The description is long, but every section earns its place given the 11 parameters and two distinct modes. It is well-structured with a summary, mode explanations, an Args list, Returns format, and two concrete examples. Information is front-loaded, and the format makes scanning easy.

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

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

The description covers the full behavior of the tool, including exact and fuzzy modes, operator semantics, pagination, sorting, projection, output shape, and example calls. For a read-oriented search tool with no annotations, this is complete enough for an agent to select and invoke it correctly without further clarification.

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

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

Schema description coverage is 0%, but the description compensates completely by documenting every parameter with types, defaults, formats, and examples. It explains the structure of conditions, the supported operators, limits on limit, the meaning of fuzzy_threshold, and the projection behavior of columns. This is exemplary parameter documentation.

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

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

The description opens with a specific verb and resource: 'Search rows with exact filters, or typo-tolerant fuzzy matching, with sorting and pagination.' This clearly distinguishes it from siblings like get_row (single row lookup) and summarize_dataset (aggregation). The two search modes are explicitly named and explained, making the tool's purpose unmistakable.

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 guidance on when to use exact mode versus fuzzy mode, including the conditions required for each and examples. It does not explicitly contrast search_rows with sibling tools like get_row or validate_rows, so there are no exclusion rules, but the usage context is otherwise well defined.

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. It clearly discloses that it returns aggregates, never dumps rows into the conversation, and provides the exact return structure. It does not explicitly state whether the dataset is modified, but the summarize intent and output shape strongly imply a read-only operation.

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-structured and front-loaded: purpose, when to use, arguments, return format, and an example. Every section earns its place without unnecessary 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?

Given the low complexity (one parameter) and the detailed return schema embedded in the description, an agent has everything needed to invoke the tool correctly. The example call is clear and the return shape 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?

The single parameter has no schema description (0% coverage), so the description must compensate. It does by specifying 'Exact dataset name' and giving an example, which is adequate for a single string parameter. It could add guidance on discovering valid dataset names, but the example removes most 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?

The description begins with a specific verb and resource: 'Summarize a dataset with aggregates instead of raw rows.' It further distinguishes itself from row-returning siblings by explaining it returns row count, numeric stats, and enum breakdowns rather than rows.

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

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

It gives explicit context: 'Use this when the user asks for totals or breakdowns' with concrete examples. It does not explicitly name alternatives such as search_rows, but the contrast with raw rows implicitly routes the agent away from row-level 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?

With no annotations, the description carries the full behavioral burden and exceeds it: it discloses that only provided fields change, every stored row is revalidated, invalid rows are preserved and reported with errors, and renaming moves values. It also documents success and error return shapes.

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 purpose and side effects, then organized into compact Args, Returns, and Example sections. Every sentence adds useful information; the example is illustrative rather than redundant.

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

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

For a mutation tool with no annotations and no parameter descriptions in the schema, this description is complete: it explains side effects, validation behavior, error cases, return contract, and invocation via a realistic example. 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 input schema has 0% description coverage, but the Args section fully compensates: dataset is defined as an exact name, column as the current column name, and changes is illustrated with concrete examples like {'max_value': 10} and {'name': 'full_name'}. The example call reinforces the parameter shapes.

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 states a specific verb ('Change'), a concrete resource ('a column'), and the scope ('existing dataset'). Naming 'name, type, or constraints' clearly distinguishes it from sibling tools like add_column and remove_column.

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 clearly establishes that this is for modifying an existing column and requires the current column name. However, it does not explicitly name alternatives or say 'use add_column instead when adding a new column', so it stops short of full routing guidance.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it explains that only provided columns change, that validation happens against the full row, that invalid rows remain untouched with plain-language errors, and how dry-run preview works before the real update. Return shapes are also given for all three operation modes.

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 organized into summary, args, returns, and an example. It is detailed but every section earns its place; the returns section is particularly valuable for distinguishing the three possible response shapes.

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

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

For a mutation tool with five parameters and nested objects, this is complete: both invocation modes are covered, all parameters are explained with examples, the dry-run safety workflow is explicit, and return values are specified. Nothing an agent needs to call it safely 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 description coverage is 0%, but the description fully compensates by documenting each parameter with concrete examples, including the exact dataset name requirement, the structured conditions filter, and the mutual exclusivity of row_ids and conditions. This goes far beyond the raw schema types.

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 ('Update rows') and clearly distinguishes two modes: explicit ids and filter-based bulk updates. This makes the tool's scope immediately clear and differentiates it from sibling tools like search_rows, add_rows, and delete_rows.

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

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

It provides precise when-to-use guidance: bulk mode defaults to a dry-run preview, the user should review it before applying, and the agent is explicitly instructed to never set dry_run=false on the first call when a filter may match many rows. This is actionable and prevents risky behavior.

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 provided, the description carries the full burden and does well: it explicitly states no writes occur, discloses the 100-row per call cap, describes normalization of valid rows, and documents the exact return structure including valid and invalid result shapes.

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 with purpose, usage guidance, args, return shape, and an example. Every section adds value and is front-loaded with the core non-destructive behavior.

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

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

For a validation tool with no annotations, the description is complete: it covers what the tool does, when to use it, parameter semantics, limits, return format, and provides a concrete invocation example.

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 dataset as an exact name with an example, and rows as a list of row objects with a max count. It could add detail on how row keys map to schema fields, but the example and context make the parameters actionable.

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: 'Validate rows against a dataset's schema without saving anything.' This both states the operation and differentiates it from sibling tools like add_rows or update_rows by emphasizing the dry-run nature.

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 this to pre-check data before committing it,' with a concrete example scenario. It does not explicitly name alternatives or state when not to use the tool, but the 'without saving anything' framing strongly implies the contrast with saving tools.

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