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

With no annotations provided, the description carries the full disclosure burden and succeeds: it states the success return format (v:{hash}), the error format (JSON with error/message), the side effect that file_path is created if missing, position insertion semantics, and format-specific output behavior (collapsed single-line GitBook HTML). This exceeds what typical descriptions disclose.

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 purpose sentence, then a clean Args block. The only waste is minor redundancy: the format distinction ('html' vs 'pipe' with collapsed single-line output) appears twice, once in prose and once in the format parameter docs.

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

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

Given no output schema, no annotations, and 0% schema coverage, the description covers everything an agent needs: purpose, all four parameters, success/error return shapes, side effects, and post-creation editing workflow. There is no meaningful gap for a create-tool of this complexity.

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

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

Schema description coverage is 0%, so the description must fully compensate — and it does. Every parameter gets real meaning: file_path includes the auto-create behavior, content includes a concrete pipe-table example, position explains 1-based-after semantics with -1 and 0 special cases, and format explains the enum values' behavioral difference.

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

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

The first sentence states a specific verb+resource ('Create a new table in a Markdown file'), and the description further distinguishes this from the edit family with 'No version hash needed — this creates, not edits' while naming read_table and write tools as the follow-up. An agent can clearly separate this from replace_table, insert_row, and update_cells.

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 workflow context: use this to create (no version hash needed), then use the returned hash with read_table and write tools for editing. It explains when the hash matters and contrasts create-vs-edit, but it does not explicitly name sibling tools as 'use this instead when X' — e.g., it never says to prefer replace_table for existing tables.

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 states the success return format ('v:{new_hash}') and error format (JSON with error and message fields), which is important for an agent to interpret results. It also implies destructive action via 'delete' but does not explicitly state that the operation is irreversible or any permission requirements. The optimistic concurrency mechanism via version is transparent, adding value beyond the schema.

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

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

The description is efficiently structured: a one-line summary, then return behavior, then a parameter list. It front-loads the essential purpose and prerequisites, and every sentence adds value. There is no fluff or redundancy, and the format is scannable for an agent.

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

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

For a tool with 4 required parameters, no output schema, and no annotations, this description covers all essential aspects: purpose, preconditions (version hash), parameter semantics, and return format. It also implies error handling. While it does not enumerate edge cases (e.g., stale version, non-existent column), the error JSON mention covers general failures. Given the tool's complexity and the lack of structured metadata, the description is comprehensive and 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 description coverage is 0%, so the description must fully compensate for missing parameter documentation. It does this admirably: file_path is defined as 'Absolute path to the Markdown file,' table_index as '0-based table index from list_tables,' version as '12-char hex hash from read_table (after "v:"),' and column as 'Column letter ("A"), name ("Priority"), or composite ("B:Priority").' This level of detail far exceeds what the schema provides and gives the agent precise instructions for each argument.

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

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

The description opens with a clear, specific verb and object: 'Delete a column.' It also specifies the required dependency on a version hash from read_table, which distinguishes it from sibling tools like insert_column and rename_column. The distinction is clear and 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 states the prerequisite of obtaining a version hash from read_table, which guides the agent on when to call this tool (after read_table). It does not explicitly state when not to use it or mention alternatives like insert_column or rename_column, but the verb 'delete' and the parameter details strongly imply the use case. A brief mention of alternative tools would push this to 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 it does well by specifying success output (`v:{new_hash}`), error output shape, and the requirement for a version hash. It could further disclose permanence/irreversibility or version-conflict behavior, but the provided details are substantive and actionable.

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 well-organized: one-line purpose, two concise behavior notes, then a clean Args list. Every sentence adds necessary information, and the critical success/error format is front-loaded before parameter 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 delete operation with no output schema and no annotations, the description covers purpose, prerequisites, all parameter semantics, success response, and error response. An agent has enough information to invoke the tool correctly and interpret the result without guessing.

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 Args block is essential and fully compensates. Each parameter gets meaningful detail: file_path is absolute, table_index is 0-based and sourced from list_tables, version is a 12-char hex hash from read_table, and row_index explicitly excludes the header row. This goes far beyond the 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 opens with a specific verb and resource: "Delete a row." It then clarifies the row is in a Markdown file at a given path and table index, which distinguishes it from siblings like delete_column and insert_row. An agent can immediately understand what action this tool performs.

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 contextual requirements: the caller must supply a version hash from read_table and a table index from list_tables. It does not explicitly name alternatives or state when not to use it, but the prerequisites and operation type make the intended usage obvious.

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 discloses the version hash requirement (optimistic concurrency), that existing rows are populated with default_value (empty string if omitted), and specifies the exact return format on success (`v:{new_hash}`) and error (JSON with 'error' and 'message'). It also explains the position parameter behavior, including the -1 append default. This is thorough and 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 efficiently structured: it leads with the core action, then prerequisites, defaults, return format, and a parameter list. Every sentence contributes value – no filler or redundancy. The layout is easy to scan and front-loaded with the most critical 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?

For a 6-parameter tool with no output schema and no annotations, the description covers all necessary context: prerequisites (version hash), behavior for existing rows, return format on success and error, and explicit semantics for every parameter. An agent has everything needed to call the tool correctly.

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

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

Schema description coverage is 0% – the schema provides no parameter descriptions. The description compensates fully by explaining each parameter: file_path as absolute path, table_index as 0-based from list_tables, version as 12-char hex hash after 'v:', name as header text, default_value as value for existing rows (default empty string), and position as 0-based index with -1 append right. This adds substantial meaning beyond the 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 'Insert a new column' – a specific verb and resource. It also mentions the requirement of a version hash from read_table, distinguishing it from sibling operations like insert_row, delete_column, and rename_column. The purpose is unambiguous and clearly 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 explicitly states 'Requires version hash from read_table', which establishes the prerequisite context and implies when to use the tool (after a read). It explains position semantics and defaults, but does not name alternative tools or explicitly state when not to use it. This is clear context, though not exhaustive exclusions.

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

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

With no annotations provided, the description carries the behavioral disclosure burden and does so well: it states that omitted columns default to empty strings, that success returns only 'v:{new_hash}', and that errors return a structured JSON payload. It also reveals the optimistic-concurrency requirement by requiring the version hash.

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, then organized into a clear Args block. Every sentence contributes useful information, and the example values dict is compact but highly informative.

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 five required parameters, no annotations, and no output schema, the description covers all essential invocation details: parameter semantics, return format, error format, and prerequisite calls. An agent has enough information to call this tool correctly and interpret its result.

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 explain parameters, and it does. It defines absolute paths, 0-based indexing, the 12-char hex hash format, the -1 append convention, and gives a rich example of the values dict with three accepted column identifier forms.

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 the specific verb-resource pair 'Insert a new row', which clearly distinguishes the tool from row-mutating siblings like update_cells and delete_row, and from insert_column. The scope is unambiguous: adding a single row to a table.

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

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

The description gives concrete context for when to use the tool: it requires a version hash from read_table and a table index from list_tables, establishing a clear workflow dependency. It does not explicitly name alternatives or state when not to use it, but the prerequisites and insertion semantics are sufficiently clear.

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

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

With no annotations, the description bears the full disclosure burden and does well: it documents the exact per-table output format (T-index, format, row/col counts, version hash, column names, row preview) so the agent knows what to expect. It stops short of explicitly stating the operation never modifies the file or describing error behavior (e.g., missing file, empty table list), which would round it out.

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

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

Purpose and usage guidance are front-loaded, followed by a compact output-format spec and param docs; every section earns its place. The format block is essential because there is no output schema to spell out the return contract, and it is presented 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 two-parameter read-only tool with no annotations or output schema, the description covers purpose, output contract, cross-tool usage, and parameter semantics thoroughly, making it callable without consulting siblings. Small gaps: no error/edge-case handling and no explicit non-mutation statement, but neither blocks 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%, and the description fully compensates: file_path is given the added requirement of being an absolute path, and preview_rows is explained as the number of data rows to preview with default and 0-means-none semantics — both beyond the schema's bare type/default fields.

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

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

Opens with a specific verb and resource ('List all tables in a Markdown file'), then names what the output contains (column descriptors, row previews). It differentiates from siblings by directing data-lookup use to search_tables and positioning itself over grep for structure discovery.

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 states when to prefer this tool ('Prefer this over grep for discovering table structure') and routes to the alternative ('Use search_tables to find specific data across tables'). Also instructs that the returned table_index feeds read_table and write tools, making cross-tool flow clear.

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

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

With no annotations, the description carries the full burden—and it delivers: it discloses the exact output format, the metadata line structure, the 12-char hash extraction rule, and what to do on STALE_READ. This goes well beyond a generic 'reads a table' statement.

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

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

The description is front-loaded with the core purpose, then metadata format, then stale-read handling, then arguments. It is somewhat long, but every sentence carries useful information and the structure is logical. Slightly tighter phrasing could earn a 5.

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

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

For a two-parameter read tool with no output schema and no annotations, the description is complete: it explains output format, how to use the returned hash, how to recover from version conflicts, and what each parameter means. Nothing needed to call the tool correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate—and it fully does. file_path is defined as 'Absolute path to the Markdown file' and table_index as '0-based table index from list_tables (the number after T).' Both parameters are given meaning and context 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 states a specific verb+resource: 'Read a full table as a clean pipe table with version hash.' It distinguishes itself from siblings by emphasizing it is the read operation ('Prefer this over reading files directly') and by covering what other table tools do not (HTML tables, inline formatting, version hash).

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 prefer this over reading files directly and gives a concrete use case ('returns the version hash needed for any edit'). It also provides recovery guidance for STALE_READ. However, it does not explicitly contrast with sibling search_tables or clarify when search would be more appropriate than a full read, so the guidance is clear but not exhaustive.

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

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

With no annotations present, the description carries the full behavioral disclosure burden. It does this well by specifying exact success output (`v:{new_hash}`), error output format, the requirement for a fresh version hash, and the guarantee that row data is unchanged. It could add more about reversibility or effects on references, but the provided transparency is above average.

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 behavior, then gives success/error behavior, then lists parameters in a clean Args block. Every sentence carries useful information and there is no filler or 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?

Given there is no output schema and no annotations, the description covers the essentials completely: operation semantics, prerequisites, parameter meanings, and return/error formats. An agent has enough detail to call this tool correctly without needing to open sibling tool definitions.

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. Every parameter is explained: file_path, table_index, version with its 12-char hex hash format, old_name with accepted forms, and new_name. This adds meaning well beyond the bare schema property names.

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: 'Rename a column header.' It clearly distinguishes the operation from row-level edits by noting 'Row data is unchanged,' and the header focus separates it from insert/delete column siblings without requiring the agent to infer anything.

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 use: it renames a column header, leaves row data alone, and requires a version from read_table. It does not explicitly name alternatives or say when not to use it, but the 'Row data is unchanged' caveat and prerequisite guidance make the intended scenario clear.

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

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

With no annotations, the description carries the full burden and succeeds: it specifies success return format ('v:{new_hash}'), error format (JSON with 'error' and 'message'), and a notable side effect (preserving the original file format, including GitBook HTML attributes). It also implies concurrency control by requiring a version hash.

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 lean and front-loaded: action, key prerequisite, input format, and behavior, followed by a readable argument list. No unnecessary fluff or 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?

Given there is no output schema and no annotations, the description covers all essential information: parameter requirements, expected input format, return and error behavior, and file format handling. An agent has everything needed to invoke 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 schema provides zero descriptions, but the Args section explains every parameter in detail: file_path is an absolute Markdown path, table_index is a 0-based index from list_tables, version is a 12-char hex hash after 'v:', and new_content is a full pipe table string. This fully compensates for the schema's lack of 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 action and resource: 'Replace an entire table with new content.' It distinguishes this tool from sibling operations like update_cells or insert_row by scope, and reinforces the Markdown context by mentioning pipe tables and GitBook HTML preservation.

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 prerequisites: version must come from read_table and table_index from list_tables, which defines the intended workflow. It does not name sibling alternatives, but the phrase 'entire table' and the requirement to provide full new content make the usage context clear enough for an agent to select it correctly.

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, and it delivers: it discloses the two search modes, the precedence rule ('regex overrides pattern'), case-insensitive behavior, the all-rows fallback, and the returned fields including version hash for follow-up writes.

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 detailed but well-organized into purpose, return value, usage guidance, mode semantics, and parameter explanations. Every sentence adds functional value, and the most important behavior 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?

Given five parameters, no output schema, and no annotations, this description is remarkably complete. It explains what the tool returns, how modes interact, what each parameter means, and when to use the tool, 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 detailed Args section is essential. It adds real meaning beyond the schema: 'Absolute path to the Markdown file,' '0-based' table indexing, and 'letter, name, or composite' for column selection.

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 precise verb and resource: 'Search for rows matching a value across one or all tables in a file.' It further clarifies the return payload (matching rows with table index, row index, version hash), making it easy to distinguish from sibling read/write 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 gives clear usage context: 'Prefer this over grep for table data — it understands column structure and handles HTML tables' and explains how it fits into a write workflow. It explicitly names grep as an alternative, though it does not directly compare itself to sibling tools like read_table.

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 full behavioral disclosure. It specifies the exact success return format, the error JSON shape, the STALE_READ recovery workflow, row indexing semantics, and accepted column formats.

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 structured with a short summary followed by bullet point format definitions, return behavior, and per-argument explanations. Every section adds necessary operational detail 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?

Given no annotations and no output schema, the description covers the full calling context: prerequisites, argument semantics, success and error responses, retry logic, and data indexing rules. An agent can invoke and recover from failures without external knowledge.

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

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

Schema description coverage is 0%, and the description compensates fully. It explains every parameter in Args, adds semantic detail absent from the schema, and precisely documents version as a 12-char hex hash and column as letter/name/composite.

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 'Batch-update cells,' a specific verb and resource that clearly states the operation. It also names the prerequisite version hash and the update object shape, distinguishing it from sibling tools like insert_row and replace_table.

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

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

The description clearly conveys when to use this tool: after reading a table to obtain a version hash. It includes explicit retry guidance for STALE_READ errors but does not explicitly contrast the tool with siblings or state when not to use it.

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