Server Quality Checklist

Tool Scores

• delete_block_rowsA
  4.3/5.0
  Behavior5/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds significant behavioral detail: missing keys are silently ignored, sheet rows are also deleted (with the assumption of one block per sheet-row), and the special behavior when deleting all rows (last row kept and cells cleared) explained by an engine constraint. This goes far beyond the annotations to disclose real-world behavior and edge cases.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with the primary purpose, followed by key behavioral notes and an edge case. Every sentence contributes value without redundancy or fluff, making it optimally concise and structured.

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

  Completeness5/5

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

  For a tool with two simple params and no output schema, the description covers essential aspects: what it deletes, how deletion works (by key), side effects on sheet rows, and the critical edge case of deleting all rows. This is sufficient for an agent to understand scope and limitations without further documentation.

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

  Parameters3/5

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

  The input schema has no descriptions (coverage 0%), so the description must supply meaning. It clarifies that 'keys' are row keys used to select rows for deletion, but does not explain the format or structure of these keys (e.g., whether they are numeric IDs or string labels). The 'block' parameter is only implied as the target block identifier, with no additional detail. The description adds some meaning but leaves gaps.

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

  Purpose5/5

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

  The description clearly states 'Delete rows from a block by their key', specifying the action (delete), resource (block rows), and method (by key). This distinguishes it from siblings like add_block_rows, move_block_row, and set_block_cells, which perform different operations on block rows.

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

  Usage Guidelines3/5

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

  The description provides context about side effects (deletes matching sheet rows) and an important edge case (keeps the last row when deleting all), which helps users understand when this tool is appropriate. However, it does not explicitly name alternative tools or state when not to use this tool, leaving the usage boundaries implicit rather than explicit.

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

• save_workbookA
  4.3/5.0
  Behavior5/5

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

  Despite annotations being minimal, the description extensively discloses behavior: default path (opened from or last saved), what is saved (values, formulas, block structure), the BLOCKREF issue and one-way resolution, and the result carrying a link instead of bytes. This goes far beyond the annotations and provides critical behavioral context.

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

  Conciseness4/5

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

  The description is somewhat long but well-structured: purpose first, then defaults, then a critical warning about block refs, and result behavior. Every sentence contributes necessary information, but the length could be trimmed if some details were in schema or annotations. No wasted words, but not maximally concise.

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

  Completeness5/5

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

  For a save operation with no output schema, the description covers all important aspects: destination, what data is persisted, Excel compatibility nuances, one-way export, and return format (link). It also implies the tool's role in the overall workflow. This is comprehensive for its complexity.

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

  Parameters4/5

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

  Schema coverage is 100% with both parameters described, but the description adds meaningful context: path defaults and when to set resolve_block_refs (Excel vs round-trip, one-way nature). This goes beyond the schema, so it earns above the baseline 3, though it doesn't introduce new parameter syntax.

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

  Purpose4/5

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

  The description clearly states the tool writes a workbook to a real .xlsx file for the human to open. It distinguishes from sibling tools by emphasizing 'real .xlsx file' and 'hand your work back', but does not explicitly differentiate from export_xlsx, so it lacks explicit sibling differentiation. Thus, it's clear but not fully distinguishing.

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

  Usage Guidelines4/5

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

  It explicitly states when to use the tool ('do it when the task is done') and provides detailed guidance on when to set resolve_block_refs (for Excel vs round-trip). However, it does not mention when not to use it or alternatives like export_xlsx, so it lacks exclusions. This is clear context but with no explicit alternatives.

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

• get_cellsA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the description builds on that by adding key behaviors: returns only non-empty cells, includes A1 ref, value, and formula, and enforces a 500-cell per call limit. This is useful beyond the annotations, though it doesn't cover edge cases like error handling or empty results.

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

  Conciseness5/5

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

  Three sentences, each earning its place: what the tool does, what it returns and how to use it, and the operational limit. No filler or repetition.

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

  Completeness4/5

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

  For a read-only tool with no output schema, the description adequately explains the return shape (non-empty cells with A1 ref, value, formula) and the 500-cell cap. It could mention behavior for out-of-range indices or fully empty ranges, but these are minor gaps.

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

  Parameters3/5

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

  Schema coverage is 100% with each parameter already described as zero-based and inclusive. The description reiterates the parameter order but adds no new meaning beyond the schema, so the baseline score of 3 for high schema coverage applies.

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

  Purpose5/5

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

  The description clearly states the tool reads values and formulas in a rectangular cell range, with a specific verb ('Read') and resource ('rectangular range of cells'). It also distinguishes itself from the sibling eval_formula by noting that for a single computed result you'd use that tool instead.

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

  Usage Guidelines5/5

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

  Explicitly says 'Use this for ordinary "what is in these cells" questions' and directs to eval_formula for a single computed result. This provides clear when-to-use and when-not-to-use guidance with a named alternative.

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

• set_cellsA
  4.4/5.0
  Behavior4/5

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

  The description discloses key behaviors: atomicity (one undo step), clearing cells with null/empty string, and the 200-cell limit. Given annotations already show mutability (readOnlyHint=false) and non-destructive (destructiveHint=false), the added details on clearing and atomicity add value beyond annotations.

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

  Conciseness5/5

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

  The description is compact, front-loaded with the core purpose, and each sentence serves a distinct function: purpose, addressing/content rules, usage preference, and limit. No redundancy or filler.

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

  Completeness4/5

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

  Given the tool's moderate complexity (2 params, array of objects) and lack of output schema, the description covers essentials: how cells are addressed, content types, clearing, block preference, and call limit. It does not mention error handling or response format, but that is less critical for a write operation. The description is complete enough for an agent to invoke correctly.

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

  Parameters3/5

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

  Schema coverage is 50% (only 'content' and 'row'/'col' descriptions are in schema; 'sheetIdx' and the array structure are not fully described). The description adds meaning about cell content types (literal vs formula) and the clearing behavior, but it doesn't explain 'sheetIdx' beyond the schema's own comment. With partial coverage, the description partially compensates but not fully.

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

  Purpose5/5

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

  The description clearly states the tool writes one or more cells in a single atomic transaction, with specific addressing and content types. It distinguishes itself from the sibling 'set_block_cells' by emphasizing plain, non-block cells, and notes that block cells should use the sibling tool.

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

  Usage Guidelines5/5

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

  It explicitly says 'For cells that belong to a block, prefer edit set_block_cells' and 'use this for plain, non-block cells,' providing clear when-to-use and when-not-to-use guidance with an alternative tool named.

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

• describe_blockA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds valuable context: it mentions the source is 'the Rust schema, the engine's authoritative source', and explains the default behavior of include_rows to save tokens. No contradictions or gaps in behavioral expectations.

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

  Conciseness5/5

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

  The description is concise yet information-dense. The first sentence encapsulates the core purpose, and the second paragraph efficiently explains an optional parameter with clear reasoning. No wasted words; each part contributes to understanding the tool's behavior.

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

  Completeness5/5

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

  Given the tool's complexity (returns schema fields, validation, editability rules) and the absence of an output schema, the description fully covers what the agent can expect: identity, per-field schema details, row keys, and optional cell values. It also clarifies the default behavior, making it complete for the agent's decision-making.

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

  Parameters4/5

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

  Schema coverage is 100% and both parameters are described in the schema. The description goes beyond by specifying the exact structure of the returned data (e.g., rows[].values[fieldName]) and explaining the token-saving rationale for include_rows, which adds meaningful semantic detail without repeating schema content.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: returning a block's full structure including identity, per-field schema with detailed elements (name, position, value_formula, validation, editability rules), and row keys. It distinguishes itself from siblings like list_blocks (which likely only lists block names) and get_cells (which retrieves cell values) by emphasizing the structural/schema role.

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

  Usage Guidelines4/5

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

  The description provides explicit guidance for the include_rows parameter ('Off by default to save tokens — use it when the agent actually needs to inspect data, not when it only needs the shape'), which helps decide when to set that flag. It does not explicitly contrast with alternative tools, but the purpose is clear enough to infer appropriate usage. A slight boost would come from naming specific alternatives, but the current guidance is practical.

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

• list_blocksA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds context about derived_fields rejecting writes and the orientation purpose, without contradicting annotations. It doesn't describe side effects, but annotations suffice; the added detail about returned data is a bonus.

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

  Conciseness3/5

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

  The description is front-loaded with the main purpose and returns a clear structure of paragraphs, but includes tangential information about next_block_start and create_block that isn't directly needed for using list_blocks. This slightly dilutes conciseness, though each sentence carries some value.

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

  Completeness4/5

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

  With only one optional parameter and no output schema, the description adequately explains the tool's output: per block it returns ref name, fields, key_field, and derived_fields. It also points to describe_block for further details, making the tool self-contained for an agent to understand its output and usage.

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

  Parameters5/5

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

  Parameter schema coverage is 0%, so the description is the sole source of meaning. It fully explains the sheet parameter: omitting it scans the whole workbook, passing it restricts to one sheet. This provides complete semantic clarity beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool lists every sheet, every block, and the fields per block, with specific details about returned metadata (ref name, fields, key_field, derived_fields). It distinguishes itself from describe_block by positioning itself as a high-level orientation tool, so purpose is specific and unambiguous.

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

  Usage Guidelines5/5

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

  Explicitly provides when-to-use guidance: use describe_block when needing field rules or row keys/values, and explains sheet parameter behavior (omit for whole workbook, pass for single sheet). This clearly differentiates usage from alternatives and gives contextual direction.

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

• list_violationsA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context about advisory semantics, host UI warning markers, and the pull-based polling rationale. However, the phrase 'return every cell' is slightly at odds with the `limit` parameter default of 50, so the limit's effect is not fully disclosed.

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

  Conciseness5/5

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

  Well-organized into three short paragraphs: purpose, when-to-use, and filter/polling behavior. Every sentence contributes; the pull-based rationale is relevant for an LLM agent deciding whether to poll or rely on push.

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

  Completeness4/5

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

  Covers purpose, usage triggers, filter composition, advisory semantics, and polling rationale. Gaps remain around the exact return shape and how `limit` interacts with the 'every cell' promise, and there is no output schema to fill those gaps.

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

  Parameters4/5

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

  Schema covers 2/3 parameters (block and sheet) with descriptions; the description adds 'omit both... to scan the whole workbook; pass either to narrow,' clarifying filter composition. The `limit` parameter receives no additional semantics beyond the schema's default/minimum, and the 'every cell' wording makes the cap less clear.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Scan validation shadow cells and return every cell whose validation formula currently evaluates FALSE.' It clearly distinguishes this from sibling tools like get_cells or eval_formula by focusing specifically on validation failures.

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

  Usage Guidelines5/5

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

  Explicitly states when to use: 'Use this when answering why is something red?, what's broken after my last edit?, or before committing a multi-step build...' It also explains filter composition and how to omit or pass block/sheet to narrow the scan.

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

• add_block_rowsA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behaviors: auto-materialization of value_formula fields, auto-installation of validation/editability shadows, and the side effect of inserting sheet rows that shift downstream rows. These are significant behavioral details not captured in the schema or annotations, fully meeting the transparency burden.

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

  Conciseness5/5

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

  The description is dense but efficient, covering all essential aspects in three sentences. It front-loads the core purpose and then logically proceeds to positioning, key requirements, engine behavior, and side effects. No fluff or redundancy.

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

  Completeness5/5

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

  Given the tool's moderate complexity (4 params, no output schema), the description is thorough: it explains default behavior, alternate insertion modes, value constraints, automatic shadow installation, and sheet row impact. The only minor omission is a stated return value, but that is not critical for a write operation and is not required since no output schema exists.

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

  Parameters4/5

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

  Schema coverage is 75%, so the description adds value by clarifying that rows require a key and values are keyed by field name—though this partly repeats schema. The crucial addition is the caution about value_formula fields ('don't pass them in values'), which is not in the schema. This elevates understanding of the values parameter beyond the basic schema description.

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

  Purpose5/5

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

  The description opens with 'Add rows to an existing block' – a specific verb (add) + resource (block) that clearly distinguishes from siblings like delete_block_rows and move_block_row. It also explains the default append behavior and positional insertion via after_key/before_key, leaving no ambiguity about the tool's function.

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

  Usage Guidelines4/5

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

  The description provides practical guidance: append is default, insertion can be placed with after_key/before_key, and value_formula fields should be omitted. However, it does not explicitly contrast with alternative tools (e.g., set_block_cells) or state when not to use this tool, so it falls short of perfect guidance.

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

• create_sheetA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses idempotent behavior (returns existing index without duplicate), return value, and implicit invocation context. This adds significant behavioral context that annotations alone do not provide.

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

  Conciseness5/5

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

  The description is three sentences, each earning its place: function, idempotency/return, and usage guidance. No redundant information, and it is well-structured with a clear sequence.

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

  Completeness5/5

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

  For a simple one-parameter tool with no output schema, the description is complete. It covers purpose, return value, idempotency, and when to call directly vs. implicitly. Nothing essential is missing.

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

  Parameters3/5

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

  The input schema covers 100% of the single parameter 'name' with a clear description ('Sheet name.'). The tool description does not add additional parameter semantics, but the schema already suffices, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Create a new sheet in the workbook' and mentions the return value (sheet index). It effectively distinguishes this from sibling tools like create_block by focusing on sheet creation.

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

  Usage Guidelines5/5

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

  Explicit guidance is given: 'Typically the agent does NOT call this directly — create_block will call it implicitly when the target sheet is missing. Use it only when you want an empty named sheet up front.' This clearly states when to use and when not to, and names the alternative.

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

• goal_seekA
  4.7/5.0
  Behavior5/5

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

  The description adds significant behavioral detail beyond the readOnlyHint and destructiveHint annotations: it explains the temp-branch execution, the bisection algorithm, the monotonicity requirement, and the behavior when the bracket does not straddle (returns a non-answer). This is exactly the kind of context that helps an agent predict outcomes.

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

  Conciseness5/5

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

  The description is compact and well-structured: it starts with a clear purpose, then a short note on safety, then usage details, then algorithm behavior. Every sentence earns its place without fluff or repetition.

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

  Completeness5/5

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

  Given the tool's complexity (goal seek with bisection, optional bracket, monotonicity assumption) and lack of an output schema, the description covers all essential aspects: purpose, non-destructive nature, cell naming, bracket behavior, monotonicity requirement, and failure handling. It is fully sufficient for correct invocation.

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

  Parameters4/5

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

  Schema coverage is high (83%), so the baseline is 3. The description goes further by explaining the semantics of the `between` parameter (optional, expand outward if omitted) and how to name cells (semantic vs. coordinate). It clarifies the search process and the meaning of the bracket, adding value beyond the schema's short descriptions.

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

  Purpose5/5

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

  The description states the tool's purpose precisely: 'Find the input value that makes a chosen output equal a target' with a concrete example. It distinguishes itself from sibling tools by framing it as a question rather than an edit, which is unique among the listed mutation/set tools.

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

  Usage Guidelines4/5

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

  Provides clear guidance on when to supply a bracket ('Give `between` when you know a bracket') and how to reference cells. It also explains why to use this over iterative conversation (one call vs. many). However, it does not explicitly name alternative tools or state when NOT to use this tool, so it falls 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.

• preview_changesA
  4.7/5.0
  Behavior5/5

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

  The annotations already declare readOnlyHint=true and destructiveHint=false ya, but the description adds meaningful behavioral detail: writes go to a temp branch that is discarded, and it highlights a potential large-response performance pitfall (416 rows of diff). This is exactly the kind of context that helps an agent avoid surprises beyond the annotation hints.

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

  Conciseness4/5

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

  Three tightly-packed paragraphs, each earning its place: 1) core behavior and safety, 2) two modes, 3) output-size optimization. Front-loaded with the most important 'dry-run/safe' concept. No fluff, but the description is dense and requires some parsing; still efficiently structured.

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

  Completeness4/5

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

  For a tool with 3 params and no output schema, the description covers the modes (`changes` vs `scenarios`), how to interpret results (returns what would move, including cascades), and the `watch` parameter's purpose and advantage. It doesn't describe the exact return shape, but given dense schema descriptions, this is sufficient and complete for the complexity.

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

  Parameters4/5

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

  Schema coverage is 100%: `watch` says 'report only these cells' values instead of the full diff', `changes` 'one hypothetical... use `scenarios` for more', and each field has a description. The description complements it by explaining the semantic vs coordinate addressing for `watch` and the notion of 'cascaded recalculations' which clarifies that the diff includes more than direct writes. Builds on schema, adds value.

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

  Purpose5/5

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

  The description starts with a specific verb+resource ('Dry-run edits on the workbook'), states what it reports (what they would do), and explicitly contrasts with actual changes ('Nothing is committed'). It clearly distinguishes two operational shapes (changes vs scenarios) and mentions the optional watch filter, all in the first sentence. This strongly separates it from sibling tools.

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

  Usage Guidelines5/5

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

  The description explicitly frames this as 'the safe way to explore' instead of changing and putting it back, giving clear when-to-use context. It also explains when to use `watch` vs. getting the whole cascade incl. an explicit example of a large scenario grid. The schema reinforces with `scenarios` 'use `changes` for one.' Guidance is explicit and immediate.

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

• set_block_cellsA
  4.7/5.0
  Behavior5/5

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

  Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds significant behavioral detail: the entire transaction aborts if any change targets a non-existent block/row/field or a value_formula field, and it clarifies that null clears a cell. It also mentions atomicity, single calc pass, and single undo entry—information beyond what annotations provide. This fully aligns with the annotations, with no contradiction.

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

  Conciseness5/5

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

  The description is a single, well-organized paragraph that front-loads the main action, then covers batching, error conditions, and value types. There is no fluff or repetition; every sentence adds essential information, making it concise and easy to parse.

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

  Completeness5/5

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

  The description fully covers the tool's complexity: atomic batch behavior, validation rules, value handling (literal, formula, null), and an explicit alternative for value_formula fields. With no output schema, this is adequate for a write operation, and the description leaves no critical gaps for an agent to discover at runtime.

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

  Parameters4/5

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

  The schema has minimal descriptions (only the value parameter has a description), but the tool description compensates by explaining each parameter in prose: block ref name, row_key, field, and value semantics, including formula prefix and null clearing. It adds meaning beyond the basic types, though it could be more explicit about the format of each parameter.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Write one or more cells inside any block(s) in a single atomic transaction.' It specifies the verb (write), resource (cells in blocks), and the addressing mechanism (block ref name, row_key, field), distinguishing it from raw cell operations. This is specific and unambiguous.

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

  Usage Guidelines4/5

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

  The description explains when to use this tool (for block-based cell writes, never raw coordinates) and explicitly names an alternative (set_field_rule) for fields with value_formula. It also encourages batching as the default. However, it does not explicitly contrast with sibling tools like set_cells or mention cases where it should be avoided, leaving some ambiguity.

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

• create_blockA
  4.9/5.0
  Behavior5/5

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

  Annotations provide only readOnlyHint=false and destructiveHint=false (which the description matches — no contradiction). The description shoulders the behavioral transparency burden richly: fields[0] is always read-only, enum fields get an auto-injected whitelist validation formula, date/datetime values get converted to numeric form, and the target sheet is auto-created if missing. These are non-obvious behaviors the agent needs to know.

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

  Conciseness4/5

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

  The description is front-loaded with the core purpose and organized with clear bullets for field types, making it scannable. It is somewhat long, but every sentence earns its place by adding functional detail (e.g., enum validation behavior, editability routing). Slightly verbose in places but justifiably so.

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

  Completeness5/5

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

  Despite having nested objects, 5 parameters, and no output schema, the description is thorough: it covers all field types, prerequisites, inference rules, and side effects (auto-create sheet, auto-injected validation, read-only row-key). The separate-rules-via-set_field_rule note prevents false expectations about this tool's scope. Nothing critical is left unexplained.

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

  Parameters5/5

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

  Schema coverage is 100%, so the baseline is 3, but the description adds substantial value beyond the schema: it explains field type semantics (for each type), how type inference works from initial_rows values, the enum_id prerequisite, ISO string conversion for dates, and the block ref name's formula usage. The description meaningfully enhances parameter understanding.

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

  Purpose5/5

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

  The description opens with a specific verb+resource statement: 'Create a structured block (table) on a sheet.' It clearly defines the scope (structure + initial rows only), distinguishes from siblings (create_sheet, set_field_rule), and explains the block ref name's role. The purpose is unambiguous and well-differentiated.

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

  Usage Guidelines5/5

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

  Explicitly states when to use ('this call only declares structure + initial rows') and when not to use ('Rules are set separately via set_field_rule'). It documents prerequisites (define_enum_set for enum types), explains the auto-create behavior for missing sheets, and clarifies how field_type is inferred when omitted. This is exemplary usage guidance.

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

• eval_formulaA
  4.9/5.0
  Behavior5/5

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

  Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful behavior: private scratch cell execution, no writes to user-visible cells, automatic leading '=' insertion, and the full return type contract including error and empty cases. This exceeds what annotations provide.

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

  Conciseness5/5

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

  The description is well-structured with a clear definition, a bulleted 'Use for' section, and a brief note about the leading '='. Every sentence adds useful information with no repetition or fluff.

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

  Completeness5/5

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

  With no output schema, the description fully documents the return value shape and all possible type values. It also covers safety, use cases, and syntax details, making it sufficiently complete for an agent to select and invoke the tool correctly.

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

  Parameters4/5

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

  The single parameter expr is already well-documented in the schema with an example and the optional leading '=' note. The description adds further value by covering return types and BLOCKREF usage, but the schema already carries most of the parameter meaning, so this is strong but not a 5.

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

  Purpose5/5

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

  The description clearly states it evaluates an Excel-style formula in a private scratch cell and returns the computed value, which distinguishes it from mutation tools like set_cells or set_field_rule. The return format is also specified, 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.

  Usage Guidelines5/5

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

  It explicitly lists concrete use cases: quick checks, sanity-testing templates before set_field_rule, and BLOCKREF/BLOCKREFS lookups. It also clarifies that nothing is written to user-visible cells, implying it should not be used for write operations.

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

• export_xlsxA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds crucial behavioral context: the bytes are injected into the agent's context and cost roughly 1.4 KB of text per KB of file. This warns about significant resource consumption and explains why the sibling tool is preferred.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core purpose, followed by a concise cost/alternative explanation. Every sentence carries essential information; there is zero filler.

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

  Completeness5/5

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

  For a zero-parameter, read-only tool with no output schema, the description fully covers what the agent needs: what it returns, the cost to the agent, and when to use the sibling instead. No gaps remain.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema leaves nothing undocumented. Per the rubric, 0 params gets a baseline of 4; the description adds no parameter-specific detail because none is needed.

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

  Purpose5/5

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

  Description opens with a specific, unambiguous purpose: 'Return the workbook as base64-encoded .xlsx bytes.' It clearly identifies the verb, resource, and output format, and distinguishes itself from sibling save_workbook by framing this as the 'last resort' option.

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

  Usage Guidelines5/5

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

  Explicitly states when NOT to use it ('Last resort') and names the preferred alternative: 'Prefer `save_workbook`'. It explains the key tradeoff (bytes passing through context vs. real file+link), giving the agent actionable decision criteria.

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

• move_block_rowA
  4.9/5.0
  Behavior5/5

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

  Annotations only state readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral context: 'reordering never changes a single computed value' and 'presentation only'. This clarifies the actual impact of the operation beyond what annotations convey, helping the agent understand side effects.

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

  Conciseness5/5

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

  Three concise, purposeful sentences. The main action is front-loaded, the default behavior is stated in the second sentence, and the practical usage note is saved for the final sentence. No filler or repetition.

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

  Completeness5/5

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

  The description covers purpose, usage, default behavior, and the important nuance that reordering is presentation-only. This is complete for a simple reorder tool with a clear sibling group (add_block_rows, delete_block_rows) and no output schema needed.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying the default behavior when neither after_key nor before_key is given ('Moves to the end') and by explaining that both row and destination are addressed by key. This is useful context not present in the schema.

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

  Purpose5/5

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

  The description opens with 'Reorder a block by moving one row to a new position', which is a specific verb+resource action. It clearly distinguishes this from sibling tools like add_block_rows and delete_block_rows by focusing on reordering an existing row rather than adding or removing.

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

  Usage Guidelines5/5

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

  Provides explicit guidance on when to use and when not to use: 'Use it to match a reading order someone expects, not to change the model.' It also explains the default behavior when neither after_key nor before_key is given and references the sibling add_block_rows for the same default, helping the agent choose between siblings.

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

• open_workbookA
  4.9/5.0
  Behavior5/5

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

  The description goes beyond the annotations by disclosing a key side effect: 'replaces whatever workbook the session currently holds, discarding unsaved changes.' It also provides actionable behavioral context about base64's enormous context cost, which is not captured in the annotations.

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

  Conciseness5/5

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

  Every sentence earns its place. The description is front-loaded with the primary concept, then covers alternatives, timing, and parameter selection in a compact but complete way. No filler.

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

  Completeness5/5

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

  Given the tool's stateful behavior and optional parameter combinations, the description fully covers the essential usage context: what the tool does, when not to call it, why the current workbook is replaced, and the preferred data-passing method. No output schema is needed for this simple initialization tool.

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

  Parameters4/5

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

  The schema description coverage is 100%, so a baseline score of 3 applies. The description additionally clarifies when to use path over xlsx_base64 and explains why, enriching parameter semantics without repeating the schema verbatim.

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

  Purpose5/5

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

  The description clearly states the tool's verb and resource: 'Start the workbook you will work in.' It further distinguishes its role by explaining fresh empty workbook vs loading an existing .xlsx, which is distinct from sibling tools like create_sheet or save_workbook.

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

  Usage Guidelines5/5

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

  Explicit guidance is given for when to call ('once at the start, not between steps'), when not to call it ('you do NOT have to call it at all'), and which parameter to prefer ('Prefer path over xlsx_base64'). This is exemplary for helping an agent decide usage.

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

• convert_to_blockA
  5/5.0
  Behavior5/5

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

  Annotations only say readOnly=false, destructive=false, so the description carries the behavioral burden. It adds crucial traits: values are untouched, conversion is an in-place one-time structural change, and the block plus schema survive save/reload and behave like a created block.

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

  Conciseness5/5

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

  Every sentence earns its place: purpose, use case, sibling contrast, parameter guidance, and persistence behavior. It is front-loaded with the core action and avoids boilerplate.

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

  Completeness5/5

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

  For a 7-parameter mutation tool with no output schema, the description covers why to use it, how to parameterize it, what the result is, and how it persists. No critical operational gap is apparent.

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

  Parameters5/5

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

  Although schema coverage is 100%, the description adds meaning beyond property descriptions: position/counts must exclude the header row, header_row and fields are alternatives, and the first field is the row-key column. This materially improves correct invocation.

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

  Purpose5/5

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

  Description opens with a specific verb and resource: 'Turn a table that already exists in ordinary cells into a block, in place, without touching its values.' It also distinguishes itself from create_block, 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.

  Usage Guidelines5/5

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

  Explicitly tells when to use: 'This is how you adopt a workbook someone hands you' and contrasts with create_block, which 'is for new tables and refuses to write over existing data.' It also gives concrete instructions on supplying data-only counts and choosing header_row vs fields.

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

• set_field_ruleA
  5/5.0
  Behavior5/5

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

  The description thoroughly explains the engine behavior after the call for each rule kind (re-materialization, shadow installation, permission gate). It also discloses rejection criteria for self-referencing rules and coordinates landing on the block, and notes that leading '=' is optional—all beyond the annotations, which only provide readOnlyHint and destructiveHint.

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

  Conciseness5/5

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

  The description is long but dense with essential information. It is front-loaded with the core purpose and optionality, then logically progresses to placeholder syntax, cross-row references, constraints, and engine behavior. Every sentence contributes value, with no redundancy or filler.

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

  Completeness5/5

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

  The description is complete for the tool's complexity: it covers what the tool does, how to use each parameter, what happens after the call, and what errors are rejected. It even addresses edge cases like row reordering and template coordinates. No output schema exists, but the description sufficiently indicates the effects.

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

  Parameters5/5

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

  With schema coverage at 60%, the description adds substantial meaning to the parameters. It gives concrete examples for value_formula (e.g., multiplication, division by a named row), explains the #FIELD, #KEY, #PLACEHOLDER placeholders, and clarifies that passing null clears a rule while omitting leaves it unchanged—details not fully covered in the schema.

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

  Purpose5/5

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

  The description opens with "Attach declarative rules to a field," a specific verb+resource that clearly states the tool's function. It distinguishes three rule kinds (value_formula, validation, editability) and explains how they relate, making it distinct from sibling tools like set_cells or eval_formula.

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

  Usage Guidelines5/5

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

  The description explicitly explains when to use the tool, how to leave rules untouched vs. clear them, and provides detailed guidance on placeholders, including when to use the two-argument #FIELD for cross-row references and why BLOCKREF is forbidden. It also notes that running totals have no rule form and directs users to write those as ordinary cells, giving clear exclusions.

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

• traceA
  5/5.0
  Behavior5/5

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

  Beyond the readOnly/destructive annotations, the description discloses critical behavior: it uses the engine's dependency graph, returns semantic names for block cells, and tracks dependencies per field rather than per row, causing over-approximation. It explicitly explains the 'scope' field and approximate flag, ensuring the agent understands the interpretive caveat.

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

  Conciseness5/5

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

  The description is well-structured: starts with purpose, then usage, then behavior, then granularity caveats. Every sentence adds value and is directly relevant to correct use. Despite its length, it is not redundant; it front-loads the essential purpose and usage, followed by necessary technical detail.

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

  Completeness5/5

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

  Given the tool's complexity (dependency tracing, block granularity, approximation), the description covers all key aspects: the two directions, naming, the engine's view through references, and the interpretation of field-wide results. It lacks an output schema, but the description suffices to understand what results will look like and how to use them.

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

  Parameters5/5

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

  The description adds substantial meaning beyond the schema: it explains the two naming conventions (semantic vs coordinate) for the target parameter, clarifies the default for direction ('Both by default'), and details how results are named. This compensates for the schema's partial coverage and adds practical guidance for parameter usage.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Follow a cell's dependencies, in either direction, using the engine's own dependency graph.' It specifies both directions (precedents/dependents) and gives concrete use cases, distinguishing it from sibling tools like eval_formula by mentioning it sees through BLOCKREF and ranges.

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

  Usage Guidelines5/5

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

  Explicit guidance is given: use precedents for auditing a number and dependents before changing something. It also contrasts with formula-string reading and explains when to rely on the result granularity, including how to interpret approximate results. This gives clear when-to-use and what-to-expect context.

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