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

Annotations already declare read-only, idempotent and non-destructive, so safety is covered. The description goes further by disclosing failure semantics ('that entry has sql=null and sql_error rather than hiding the catalog') and the default exclusion of system tables, which the annotations do not convey.

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

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

Front-loaded with the what, then paging, then the sibling escape hatch, then the error contract. Efficient overall, though the 'An .accdb is an application rather than a document...' sentence is motivational exposition that could be trimmed.

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?

An output schema exists so return values need not be explained, and the description still covers the notable output contract (sql=null/sql_error, next_offsets). Nothing an agent needs to invoke it correctly is missing; remaining detail lives in the schema.

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

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

Schema description coverage is 100%, so include, offset, max_results and file_path are already documented with defaults and ranges. The description reinforces the paging pattern and mentions next_offsets, but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and three concrete resources (tables with columns, saved queries with SQL, table relationships) and explicitly frames the scope as 'what an Access database holds besides its code'. This is clearly distinguishable from siblings like xlide_list_modules and xlide_read_access_query.

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?

Names an alternative and the condition that selects it ('Long query SQL is previewed; use xlide_read_access_query for the whole text'), explains paging via include/offset/next_offsets, and gives an explicit applicability constraint ('Access files only'). Removes guesswork about when to call it.

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

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

The description discloses that the tool saves the workbook and mimics Excel's Insert Chart behavior, and it details how the data is interpreted and how placement works. It also mentions that xlide_list_shapes will report the chart afterwards. Since all annotations are false, the description carries the full burden. It covers the main mutation (saving) and data handling, but does not discuss reversibility, permissions, or failure modes, leaving some behavioral aspects undisclosed.

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

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

The description is a single, well-structured paragraph. It opens with the core action ('Adds a chart... and saves the workbook'), then provides data interpretation, placement, and verification. Each sentence adds value without redundancy. It is concise yet thorough, though slightly longer than necessary due to the detailed data-layout explanation.

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

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

Given the tool's complexity (12 parameters, output schema present), the description covers the essential aspects: what it does, how data is structured, how to position the chart, and how to confirm the result via xlide_list_shapes. It does not explicitly mention prerequisites like file being open or error handling, but these are not critical for the core usage. The description is sufficiently complete for an agent to call the tool correctly.

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

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

The schema already documents all 12 parameters with individual descriptions (100% coverage), so the baseline is 3. The description adds meaningful context beyond the schema by explaining how data_range is interpreted (first row as series names, first column as categories, and how column vs row series are auto-detected). It also clarifies placement options (cell vs left/top in points). This enrichment justifies a score above baseline.

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

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

The description clearly states the tool adds a chart of a block of cells to a worksheet and saves the workbook. It specifies the exact action and resource, and the data interpretation details (first row names series, first column categories) further clarify its function. It is distinct from sibling tools like xlide_manage_shape because it explicitly targets chart creation, not generic shape management.

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 on how to use the tool: it explains the expected data layout, how series are determined, that data can reside on another sheet, and how to place the chart. However, it does not explicitly mention alternatives or when not to use this tool, so it lacks explicit exclusion criteria. This is a minor gap given the unambiguous nature of the tool's purpose.

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?

Adds substantial context beyond the annotations: no Office installation required, nothing is executed, host-specific object-model matching (Word vs Excel vs VB6), and the semantic weight of severities. The annotations already cover the read-only/idempotent safety profile, so this is a strong additive description rather than a restatement.

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

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

Front-loaded with the core action and return shape, then guidance, then pagination. All sentences carry information, though the VB6 clause is niche and the sentence is longer than needed.

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?

An output schema exists, so return-value explanation is optional; the description nonetheless names the returned fields, and it covers purpose, constraints, severity policy, and pagination. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the pagination flow ('use offset and next_offset to read later findings'), which ties the input parameter to an output field. It adds nothing for min_severity or module_name beyond what the schema already documents.

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

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

States a specific verb (static analysis) and scope (every VBA module in an Office file), plus the exact shape of what it returns (module, line, column, code, message). The 'every VBA module in an Office file' scope implicitly distinguishes it from the source-level sibling xlide_analyze_source.

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

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

Gives explicit when-to-use ('call this after every VBA change') and an actionable operating policy (treat error severity as a build failure, re-analyze until clean, read warnings). It does not name alternatives such as xlide_analyze_source or xlide_compile_check, so the routing decision is left partly to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: no file required, no cost, errors surface here rather than in front of the user, and file_path resolves calls into the surrounding project. It does not describe result shape or error reporting, which keeps it at 4.

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

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

Four front-loaded sentences, each carrying a distinct payload (purpose, when to use, host vs file_path, pagination). The 'costs nothing, needs no file' clause slightly overlaps with the opening framing, which is the only real waste.

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

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

With an output schema present and 100% parameter description coverage, the description need not cover returns. It still covers when to call, the host/file_path trade-off, and how to page through a long result, which is everything an agent needs for a 7-parameter read-only tool.

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 100%, so the baseline is 3, but the description adds decision-level meaning the schema does not: host is for measuring against an object model while file_path overrides host and pulls in sibling modules. It also explains the offset/next_offset pagination flow, which the schema only half-documents.

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

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

The opening sentence names a specific verb and resource ('Runs static analysis over VBA source') and immediately scopes it: source held in memory, before it is written to a file. That scope is exactly what separates it from the file-based 'xlide_analyze' sibling, so an agent can route without opening either schema.

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

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

Gives a concrete when-to-use ('check code you have just generated') and clarifies it is free of side effects ('costs nothing, needs no file'). It does not explicitly state exclusions or name the alternative tool to use for already-saved modules, so it stops short of the 5 bar.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, yet the description adds real context beyond them: cached results may be stale until Excel recalculates, Excel hides ignored findings by default, and which file formats are supported. The only repetition is the return-shape sentence, which the output schema already covers.

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

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

Four dense sentences, front-loaded with the core purpose and followed by behavior caveats and pagination; every sentence carries information. Slightly cramped, and the return-value sentence is partly redundant with the output schema.

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 paginated, read-only inspection tool with a full input schema and an output schema, the description supplies everything an agent needs: trigger semantics, staleness caveat, default filtering behavior, supported formats, and paging. Nothing material 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 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies the default rules behavior (Excel's enabled rules), the ignored-findings filter, and frames offset/next_offset as pagination for long result lists. It also references next_offset, which is not an input parameter, useful for understanding the returned paging.

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

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

Specific verb (lists) plus a precise resource (cells Excel would mark with a green error-checking triangle) with concrete examples of what triggers a finding. It is clearly distinguishable from siblings like xlide_read_cells or xlide_rules without opening either schema.

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

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

The description makes clear this is the diagnostic tool for error indicators and explains the conditions that change results (include_ignored=true, formula-dependent checks using cached results). It does not name an alternative sibling or state when-not-to-use, so it falls short of a 5 but is far above bare implication.

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

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

Beyond the annotations, the description discloses critical behavioral traits: closing frees the file for write, the application stays unless this server started it and nothing else is open, unsaved copies are left open and reported, and ending the process destroys every unsaved document in it. It also reveals that the user's position is remembered and restored by xlide_open_in_app, adding real operational 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.

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

The description is dense but every sentence carries operational weight: the main action is front-loaded, and each subsequent clause addresses a real decision point or side effect. The long paragraph structure is acceptable given the destructive complexity, and no sentence is filler.

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

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

For a destructive tool with four parameters and an output schema, the description covers all the important context: when write access is freed, what happens to unsaved work, when process termination is acceptable, the platform restriction, and the restoration behavior via a sibling tool. Nothing an agent needs to safely invoke this 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 100%, and each parameter already has a detailed description, so the baseline is 3. The tool description adds some extra meaning by clarifying that file_path refers to a file currently open in Office and by explaining the precedence relationship among save_changes, discard_changes, and end_process. This is modest but genuinely supplementary, so it earns a 4 rather than a 3.

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: 'Closes a file in the Office application the user has it open in.' It immediately distinguishes its scope by stating 'Only that file: the application stays,' which separates it clearly from its sibling xlide_open_in_app. The function's destructive and unlocking role is unmistakable.

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

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

The description gives explicit conditional guidance: use save_changes first when unsaved work matters, use discard_changes only with user consent, and use end_process only when the application does not answer or the file stays locked, again with user consent. It also names the alternative flow, xlide_open_in_app, for restoring the user's position, and states the Windows-only platform constraint.

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

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

Beyond the annotations, the description discloses two important behavioral traits: Excel is made visible during the check, and a hidden instance would misreport a rejection as a pass. This explains a non-obvious failure mode and gives the agent essential context for interpreting results.

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

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

The description is compact and front-loaded with the core function, then platform constraint, then sibling guidance, then the visibility caveat. Every sentence contributes useful, non-redundant information and no filler is present.

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

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

For a tool with two fully documented parameters, a rich schema, and annotations covering read-only/idempotent behavior, the description adds the remaining context an agent needs: platform limitation, when to choose it versus the analyzer, and the visible-Excel behavior. Return values are covered by the output schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents file_path and timeout. The description mentions compiling 'a file's project' but does not add meaningful parameter-level detail beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: asks the real VBA editor to compile a file's project and reports whether it accepted it. It also distinguishes itself from xlide_analyze, naming the compiler's verdict versus a static analyzer's, so an agent can tell it apart from a closely related sibling.

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 usage guidance: run xlide_analyze first because it is free and needs no Office, and use this tool when the last word matters. It also states a hard exclusion, Windows only, clarifying when the tool cannot be used.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description reinforces this by disclosing that the destination may hold data that the paste can replace and that overwrite requires user consent. It further adds non-obvious behavior: formulas move with relative references as Excel's Copy does, and it works on .xlsx/.xlsm/.xlam. This is rich context beyond the annotations.

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

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

Front-loads what the tool does, then layers paste-special options, overwrite warning, and formula semantics. Every sentence carries information, though the paste-special enumeration is dense and could be trimmed slightly.

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 10-parameter mutation tool with an output schema already present, the description covers the essential gaps: overwrite consent, formula reference behavior, supported file types, and paste mode semantics. An agent has enough to invoke it correctly and safely.

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 100%, so the baseline is 3. The description nonetheless adds interpretive meaning, e.g. that 'operation' combines values arithmetically and that skip_blanks leaves destination cells untouched, which helps an agent understand the paste-mode interaction rather than just the field list.

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

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

States a specific verb and resource ('copies a range to another cell or block, on the same sheet or another sheet') and adds a side effect ('saves the workbook'). This is clearly distinguishable from siblings like xlide_write_cells and xlide_read_cells without opening any schema.

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

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

Gives explicit conditional guidance for the risky path: 'Set allow_overwrite=true only after the user agrees to replace it.' It also explains when paste variants apply (values/formulas/formats/etc.). It stops short of naming sibling alternatives such as write_cells for outright value entry, so it is not a full when/when-not map.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, non-open-world. The description adds genuine context beyond that: the template comes from the application itself so the file opens without a repair prompt, and it never overwrites or replaces existing content. Return-value behavior is left to the output schema, which exists.

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

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

Front-loaded with the core action and scoping constraint in the first sentence; subsequent sentences carry distinct payloads (extensions, non-overwrite guarantee, sibling routing). Slightly long and dense, but no sentence is filler.

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

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

With annotations covering safety semantics, an output schema covering returns, and 100% schema parameter documentation, the description fills the remaining gaps: format selection, overwrite behavior, and the hand-off to xlide_write_module. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% for the single parameter, so the baseline would be 3. The description adds real meaning: the extension selects the format, enumerates valid extensions, and notes the one case where the path may point at an existing file rather than a new one.

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

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

States a specific verb and resource ('Creates a new Office file with an empty VBA project') plus the exact extensions supported, and clearly separates itself from xlide_write_module, which handles the first module. An agent can distinguish this from xlide_list_projects/xlide_project_info without opening a schema.

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

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

Explicitly covers when to use it (new file creation, or an existing .docm/.accdb with no project), what it will not do (never overwrites a file or replaces an existing project), and names the alternative tool (xlide_write_module) for the case of a macro-capable file saved before its first macro.

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

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

Goes well beyond the destructiveHint=true annotation by disclosing there is no undo, that the file is saved on success, the document-module restriction, and the Excel refusal when a shape-call check cannot be performed. These are exactly the behavioral traits an agent needs before a destructive write.

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

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

Four sentences, each carrying distinct safety or precondition information, with the destructive nature front-loaded. No filler or repetition of the title.

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

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

For a destructive, 5-parameter tool with an output schema already covering returns, the description supplies the safety posture, the alternative (read first), the exclusions, and the failure condition. Nothing material 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 100%, so the schema already documents all five parameters, including the rationale for allow_protected, allow_invalidate_signature, and expected_content_token. The description only indirectly reinforces the content-token idea ('stale look') and does not add syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently deletes a VBA module from an Office file and saves it'), plus the permanence qualifier. An agent can instantly distinguish it from xlide_write_module, xlide_edit_module, and xlide_rename_module.

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

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

Explicit when-to-use and prerequisites: ask the user first, read the module before deleting so it can be restored, and note that document modules cannot be deleted. It effectively routes the agent to xlide_read_module before this call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this by saying the tool 'Reports' rather than mutates, and notes it can be safely called before a test run. It adds useful context about what the report contains without contradicting any annotation.

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

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

Two sentences with no filler. The first sentence front-loads the list of reported items, and the second gives concrete trigger conditions. Every clause contributes to deciding when and why to invoke this tool.

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

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

With zero parameters and an output schema present, the description fully covers what the tool reports and when to call it. An agent has enough information to invoke it appropriately and interpret the result using the output schema.

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

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

The tool has zero parameters, so there is no parameter documentation burden on the description. The baseline of 4 applies because the description correctly assumes no inputs are needed.

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 the specific verb 'Reports' and enumerates concrete resources: workspace roots, read-only status, optional layers, and Windows Office applications. This clearly separates it from sibling operation tools like xlide_run_macro or xlide_analyze, which perform actions rather than report capabilities.

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

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

The description gives explicit trigger conditions: 'Call it when a tool reports something missing, or before promising the user a test run.' It does not specify exclusions or alternatives, but no sibling tool appears to fill this diagnostic role, so the context is clear enough.

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

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

Annotations already disclose destructive/idempotent/readOnly, so the bar is lower, yet the description still adds real behavior: units differ by host (points vs twips), null clears a property back to default, and removing a container cascades to its children. These are consequences an agent must know before calling and are not derivable from the annotations.

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

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

Four tight sentences, front-loaded with what the tool does and the three action modes, followed by the unit rule, the destructive caveat, and the sibling handoff. Every sentence carries distinct information; no filler.

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

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

For a 16-parameter mutation tool with an output schema and full annotation coverage, the description supplies the missing behavioral contract: units, cascade deletion, default-clearing semantics, and the event-procedure gap. Nothing an agent needs to call this correctly is left unexplained.

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 100%, so the schema carries most parameter meaning, but the description adds semantics the schema omits: the measurement unit (points for UserForm, twips for Access) and the null-clears-to-default behavior of set_property. Modest but genuine value over the baseline.

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

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

States a specific verb and resource and enumerates the three modes of operation (add a control, remove one, set a property). That is far more than a restatement of the name. It does not, however, distinguish itself from the sibling xlide_manage_form, which appears to overlap in scope.

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

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

Gives explicit routing guidance for one case ('Adding a control does not write its event procedure; do that with xlide_write_module') and a precondition for destruction ('ask the user first'). It never explains when to reach for this tool instead of the nearby xlide_manage_form, so the sibling coverage is incomplete.

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

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

Goes well beyond the destructiveHint/idempotentHint annotations: it discloses the concurrency guard (expected_content_token required, refuses stale edits), the non-overlap constraint, that ranges index the original source without the attribute header, that the call saves once, and that an applied edit returns a read-back diff plus a new token. This is exactly the operational detail an agent needs before a destructive mutation.

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

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

Front-loaded with the core action and save behavior, then the line-indexing convention, then the edit semantics, then the safety and preview mechanics. Every sentence carries information, though the density is near the upper limit and could be lightly trimmed without loss.

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

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

For a destructive, concurrency-guarded multi-edit tool with 7 parameters, the description covers indexing model, edit semantics, validation path, staleness protection, and the returned diff/token. With an output schema present it need not enumerate return fields, so nothing material 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 already 100%, so the baseline is 3, but the description adds real semantics: the insertion convention (end_line = start_line - 1), the empty-replacement deletion rule, the 1-based origin against xlide_read_module output minus the attribute header, and the purpose of preview_only and expected_content_token. It adds meaning beyond the schema rather than restating it.

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

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

States a specific verb set (replaces, inserts, deletes) on a specific resource (an existing VBA module), with the key differentiator 'in one existing VBA module and saves once' separating it from xlide_write_module (full rewrite) and xlide_read_module (read-only). An agent can place it precisely among the module siblings without opening a schema.

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

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

Gives clear operating context: batch line-range edits within one existing module, single save, preview_only to validate first, 'Analyze the file afterward' as a follow-up step. It does not explicitly name an alternative (e.g. use write_module to replace a whole module), so it earns 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context: 'Changes nothing', 'Uses pyOfficeEditor's formula engine, 493 of Excel's functions', and 'with the workbook's cells as they stand'. It also clarifies that the result matches what Excel would give. This adds value beyond the annotations without contradicting them.

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-structured. It opens with the primary purpose, includes a concrete example, and covers key details (engine, non-destructive, supported file types) without redundancy. Every sentence adds value, and it is not overly long.

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

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

Given the output schema exists (not shown but indicated), the description need not detail return values. It covers the tool's purpose, use cases, non-destructive nature, supported formats, and function count. This is sufficient for an agent to decide to invoke it, though it could mention any error handling or edge cases.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description does not add significant new meaning beyond the schema, though it does hint at the 'at' parameter's role in relative references. Since the schema carries the load, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it evaluates a formula in a cell context without writing it, distinguishing it from write operations. It gives a concrete example (SUMIFS) and names the specific action ('works out what a formula would give'). It differentiates from siblings by mentioning 'without writing it there' and references xlide_write_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 explicitly states when to use the tool: 'to check a formula before xlide_write_cells, or to ask the workbook a question'. It also implies the tool is non-destructive and works on the current state of the workbook. This provides clear context for an agent to decide when to invoke it versus alternatives.

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

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

Annotations already signal a destructive, idempotent write; the description adds real context beyond them: preview-by-default until apply=true, unchanged files left alone, and critically that exported files are copies that do not affect the Office file until xlide_import_modules runs. This is exactly the behavioral disclosure a mutation tool needs.

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

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

Front-loads what it does, then preview/apply semantics, then the copy relationship. Most sentences earn their place, though 'Only when the user asks for it' is slightly redundant with the preview framing and could be tighter.

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

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

With an output schema present, return values need no explanation, and the description still covers reversibility, destructive scope, and preview behavior. An agent has everything needed to invoke it safely.

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

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

Schema description coverage is 100%, so apply and file_path are already documented. The description reinforces apply's semantics (write vs preview) but does not clarify delete_stale (which the schema itself flags as requiring user confirmation), so it adds only marginal value over the 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?

States a specific verb (writes) and resource (every VBA module) plus output format (.bas and .cls), with the motivation (source control or review). It is cleanly separable from siblings like xlide_list_modules and xlide_read_module.

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

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

Gives a clear triggering condition ('Only when the user asks for it') and a context (source control/review), and names the inverse operation xlide_import_modules. It does not explicitly state when-not-to-use or contrast against other export/review siblings, so it falls short of a full 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds the specific destructive mechanism: merging clears values and formulas outside the top-left cell and requires allow_overwrite. It also documents the non-destructive incremental behavior (each cell keeps the rest of its own format) and the supported file types.

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

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

Front-loaded with the core scope, then one sentence each for pass-only semantics, color syntax, number-format semantics, merge destruction, and file types. Dense but every sentence carries distinct, non-redundant information.

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

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

For a 20-parameter mutation tool with full schema coverage, an output schema, and annotations covering the safety profile, the description supplies the remaining high-risk context (destructive merge, guard parameter, format-code side effects). Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the hex color grammar (RRGGBB/AARRGGBB, no leading hash) and the fact that the number format code determines date display. It does not restate every parameter, which is appropriate.

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 precise verb+resource scope ('Changes how a range looks') and enumerates exactly the facets it governs — bold/font, fill, borders, alignment, number format, merging. It implicitly separates itself from value-writing siblings such as xlide_write_cells by stressing that only formatting is touched and values are untouched.

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

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

It gives clear operational context — pass-only semantics, the allow_overwrite precondition for merges, and 'Ask the user first' — but never names an alternative tool or states when to prefer it over xlide_write_cells or xlide_manage_sheet. Useful context, no explicit exclusion routing.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond those: per-module/Power Query granularity, unified diff format, the fact that worksheet cell values are not compared, the default revision of HEAD, and the binary-file rationale. This is exactly the kind of added context the rubric rewards.

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 six sentences, each earning its place: core action, motivation, usage timing, a key limitation, default behavior, and requirement. It is front-loaded with the primary function and contains no redundant or filler content.

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

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

For a read-only comparison tool with a full parameter schema and an output schema, the description covers all operational essentials: what is compared, what is not compared, revision semantics, and repository prerequisites. An agent has enough information to decide whether and when to call it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does mention the revision default and that any git revision is accepted, but this is already in the schema. It does not add significant parameter-level meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Lists what changed inside an Office file since a git revision, one entry per VBA module and Power Query, with a unified diff.' This is precise and differentiates it from ordinary git diff, which the description explicitly says cannot handle the binary file format. No sibling tool has a similar focus.

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

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

It provides explicit usage timing: 'Call this before committing, and to review what an agent or a colleague changed.' It also explains why git diff is not an alternative and states the prerequisite that the file must be inside a git repository and tracked, giving an agent clear conditions for invocation.

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

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

Goes well beyond the annotations by disclosing the dry-run-by-default contract, that unmatched file names create new modules, that document modules like ThisWorkbook are written but never created, and that an unchanged plan skips the save. These details materially affect how the agent calls the tool and are not derivable from the destructive/idempotent hints alone.

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?

Six short sentences, front-loaded with what the tool does and the preview default, followed by edge cases (module creation, document modules, no-op saves) and a next-step pointer. No sentence is redundant.

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

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

With an output schema present, the description does not need to explain return values, and it covers the full behavioral envelope: default preview, write gate, creation rules, and follow-up. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so each parameter (apply, file_path, source_folder, allow_protected, allow_invalidate_signature) is already documented in the schema. The description reinforces apply semantics but adds no field-level meaning beyond it, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Reads .bas and .cls files from a folder back into an Office file's VBA project and saves it'), which is clearly distinct from the sibling xlide_export_modules. An agent can identify the direction of the operation (files → VBA project) immediately.

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?

Explains the default preview behavior and the apply=true gate, and routes the agent to xlide_analyze after a change. It does not, however, state when to prefer this over xlide_write_module or xlide_edit_module for single-module edits.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces these with 'Changes nothing.' It adds meaningful behavior beyond the annotations: Windows-only platform scope, coverage of any running instance, read-only vs. editing states, unsaved changes, and lock-holding processes.

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

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

Three compact sentences, each earning its place: the primary behavior, the usage triggers, and platform/side-effect clarifications. The main claim is front-loaded and no filler is present.

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

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

For a single-parameter read-only tool with an output schema present and safety annotations covering side effects, the description covers the key contextual facts: what states are checked, what lock information is returned, when to call it, the platform limitation, and that it mutates nothing.

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

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

Schema description coverage is 100%: the single file_path parameter is already documented as an absolute path to the Office file. The description does not add parameter-level semantics, but with full schema coverage it does not need to. Baseline 3 applies.

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

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

The description names the precise verb ('Says whether') and the resource (a file's open status in its Office application), and specifies the full scope: any running instance, read-only or editing, unsaved changes, and which processes hold the lock. This clearly differentiates it from sibling tools like xlide_open_in_app and xlide_close_in_app.

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 triggers: 'when a write reports the file is locked, before closing anything, or when the user asks.' It does not name alternatives or explicitly state when not to use it, so it stops short of the full when/when-not guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds meaningful context beyond them: an unreadable report collection is treated as a failure rather than an empty list, and unreadable designs are marked unknown via sections_error. This discloses error-handling semantics that structured fields do not.

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

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

Four sentences, front-loaded with the core purpose and return content, followed by failure semantics and pagination. Efficient and each sentence adds information, though slightly dense with the Access-specific caveats grouped mid-paragraph.

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?

An output schema exists so return shape needn't be explained, and annotations cover the safety profile. The description still fills the important gaps: error-vs-empty distinction, sections_error signaling, and pagination guidance, making it adequate 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 100%, so the schema already documents file_path, offset, and max_results; baseline 3 applies. The description adds pagination intent (using offset and next_offset) but no syntax or format detail beyond the 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?

States a specific verb (Lists) and resource (UserForms / Access forms and reports), and specifies what is returned (control count, sections). It clearly differentiates from sibling list tools like xlide_list_sheets and xlide_list_modules by naming the form/report scope.

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?

Points to the alternative for reading a design's code (xlide_read_module) and explains the pagination workflow with offset/next_offset. It does not explicitly say when to choose this over xlide_read_form or other form siblings, but the context is clearly implied by the file-scoped listing purpose.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new context by noting the returned content_token is meant to be passed to a guarded write, plus that large projects must be paged. It stops short of describing limits or what the write guard actually enforces.

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

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

Three sentences, each carrying distinct load: what is returned, when to prefer this tool over the sibling, and how to page. The returned-field list is front-loaded and the alternative routing comes before the pagination detail.

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?

An output schema exists, so return values need not be spelled out, yet the description still names the key fields and the one non-obvious one (content_token). Routing, paging and return shape are all covered; nothing an agent needs to call this 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 100%, so offset, max_results and file_path are already documented, which sets the baseline at 3. The description adds meaning beyond the schema by explaining the offset/next_offset pairing as a paging loop, which the schema alone does not convey.

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

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

States a specific verb and resource (lists VBA modules in an Office file) and enumerates exactly what is returned: name, kind, line count, content_token. The kind values are even spelled out (standard, class, document, userform), so the agent knows the shape without opening the schema.

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

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

Explicitly names the overlapping sibling xlide_project_info and gives the selecting condition: use that one for more data, use this one when the file is already known and only the module list is wanted. Also gives pagination guidance for large projects, so both the routing and the operational path are covered.

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

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

Annotations already establish readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds real value beyond that: the content_token can guard an xlide_edit_module call and paging behavior via offset/next_offset, which an agent could not infer from annotations alone.

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

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

Three sentences, front-loaded with what is returned and then usage, then paging. No filler, though the pagination sentence and the token-guard sentence are somewhat loosely tied to the main purpose.

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?

An output schema exists, so return-value explanation is not required. The description covers purpose, the edit-guard token, and pagination, which is everything an agent needs to call this read-only list tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by explaining that offset and next_offset are for paging through a module with many procedures, giving operational meaning to the pagination parameters beyond the schema's terse 'Procedures to skip.'

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

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

States a specific verb and resource ('Lists the Sub, Function and Property procedures in one module') and enumerates the returned fields (kind, scope, line number, signature). It also implicitly separates itself from xlide_read_module by framing the tool as a way to avoid reading a long module in full.

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

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

Gives a clear use case ('find where to change something without reading a long module in full') and paging guidance via offset/next_offset. It stops short of explicitly naming the alternative tools (xlide_list_modules, xlide_read_module) and the conditions that would select them.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds context those annotations cannot: the exact return fields, the fact that recognized-but-unopenable files are listed with a reason so templates/add-ins are not silently dropped, and the paging contract. It omits auth/permission notes, keeping it below 5.

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

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

Front-loaded with the core action and return shape, then the when-to-use rule, then supported formats, then edge-case behavior and pagination. The extension enumeration is long but genuinely informative for file-type expectations; nothing is filler.

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

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

An output schema exists, so return values need not be explained in prose, yet the description still clarifies the semantics of the openability field and the 'listed with reason' edge case. Together with the covered file-type matrix and paging guidance, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so offset, subfolder, and max_results are already documented in the schema. The description only restates pagination ('offset and next_offset') and even references a next_offset field that is not an input parameter. Baseline 3 is appropriate.

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

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

States a specific verb (finds/lists) and resource (Office files in this workspace) and specifies the return payload: absolute paths, host application, and VBA openability. It is clearly distinguishable from siblings like xlide_list_modules or xlide_list_sheets, which enumerate different resources.

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

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

Gives explicit invocation guidance: 'Call this first when the user has not named a file,' which is a real routing rule. It also explains pagination via offset/next_offset. It stops short of naming the sibling alternative an agent should use once a file *is* named, so it is not a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds genuinely new behavioral detail: steps is null with steps_error when M formula parsing fails, that queries exist outside the VBA project, and that pagination uses offset/next_offset.

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

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

Four sentences, front-loaded with what is listed, followed by an edge case, usage guidance, and pagination. Every sentence contributes, though it is slightly denser than strictly necessary.

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 an output schema exists, return values needn't be restated, yet the description still covers the list contents, the parse-failure edge case, and pagination behavior. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so offset, file_path, and max_results are already documented in the schema. The description only reiterates the offset/next_offset paging pattern, adding minimal meaning beyond the structured fields; baseline 3 applies.

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

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

States a specific verb and resource ('Lists the Power Query queries in an Excel workbook') and enumerates the fields returned (name, group, description, load targets, step names). This clearly distinguishes it from siblings like xlide_read_query, xlide_list_sheets, and xlide_list_modules.

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

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

Gives an explicit trigger: 'Call this when asked what a workbook does' and notes that macro-free .xlsx files can still hold most of their work here. It does not name a contrasting alternative (e.g., read_query for a single query's M code), so it stops short of full when/when-not routing.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context by explaining that reference paths and versions can cause a project to break on another machine, which helps the agent interpret results without overstepping the annotation coverage.

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

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

Two purposeful sentences front-load the core behavior and follow with high-value usage context. No wasted words or redundant restatements of the tool name.

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

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

With one well-documented parameter, full annotations, and an output schema present, the description provides everything an agent needs: what the tool lists, why it matters, and when to call it. There are no meaningful gaps.

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

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

The input schema already documents the single file_path parameter completely at 100% coverage. The description does not add parameter-level guidance, but none is needed beyond the schema's 'Absolute path to the Office file' definition.

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

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

The description states a precise action and resource: it lists the type libraries a VBA project references. It also clarifies the content of the listing—qualification name, kind, and registry/file path—making it distinct from siblings like xlide_list_projects or xlide_project_info.

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 concrete trigger scenarios: unresolved names, early-vs-late binding decisions, and machine-specific failures. It does not name an alternative tool or explicit when-not-to-use case, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description still adds real behavioral context: ActiveX controls are listed but carry no macro and their code lives as event procedures in the sheet module. That is meaningful beyond the annotations, though much of the rest describes return shape already covered by the output 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?

Front-loaded with the resource and its scope, then usage, then caveats. Every sentence carries information, but the return-value enumeration overlaps with the output schema, making it longer than strictly necessary for a tool that already publishes a return shape.

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

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

For a read tool with full annotations, a 100%-covered schema and an output schema, the description supplies the one thing that could cause a wrong call — the ActiveX/no-macro and OnAction-name-is-frozen quirks — plus the paging hint. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning the schema does not: an empty sheet means every sheet, and offset/max_results are framed as a paging mechanism for crowded sheets (it even mentions a next_offset token). Slight mismatch in that next_offset is named but not present in the input 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?

States a specific verb and resource ('Lists what sits on a worksheet's drawing layer') and enumerates exactly which artifacts are covered (buttons, form controls, AutoShapes, text boxes, pictures, charts, groups). An agent can immediately distinguish this from xlide_list_sheets or xlide_list_forms.

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

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

Gives concrete triggers ('when asked how a workbook is started, or before renaming a Sub') and explains why the second matters (OnAction names a procedure and nothing rewrites it). It also routes crowded-sheet reads to sheet/offset pagination, naming the alternative behavior explicitly.

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

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

With readOnlyHint, idempotentHint, and destructiveHint=false already covering the safety profile, the description adds substantial behavior context: format support differences, the Windows/Excel requirement for .xlsb and .xls, the reduced survey on that path, and error markers such as hidden_error and pivot_tables_error. It also states that malformed surveys are refused rather than returned partially.

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 and keeps most sentences informative. It is slightly repetitive, since the first sentence lists pivot tables, chart sheets, and named ranges and the third sentence revisits that support on .xlsx/.xlsm/.xlam, but the repetition serves format-specific clarity.

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 that an output schema exists, the description need not explain return values, and it already covers the important behavioral edges: supported formats, degraded .xlsb/.xls behavior, error markers, and refusal on malformed surveys. Nothing an agent needs to invoke the tool correctly appears to be missing.

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

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

Schema description coverage is 100%, so file_path and timeout are already documented in the schema. The description does not add syntax, format, or argument-level meaning beyond what the schema provides, 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.

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

The description states a specific verb and resource: list worksheets in an Excel file, with an explicit inventory of what is returned (used ranges, hidden state, pivot tables, chart sheets, named ranges). It also distinguishes the tool from cell-reading siblings by telling the agent to call it before reading 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?

It gives a clear when-to-use condition: call before reading cells so the requested range is known to hold data. It also documents format-dependent behavior for .xlsx/.xlsm/.xlam versus .xlsb/.xls. It stops short of naming explicit alternatives or when-not-to-use cases, so it is strong 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?

Beyond the read-only/idempotent annotations, it discloses that this read includes unsaved edits, can differ from the file read, and that surface_only=true reads the editor's own copy only for an open tab. It also explains slice behavior via start_line/end_line.

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 and sibling comparison, then adds conditional details. It is mostly efficient, though the content_token sentence is not tied to an input parameter and slightly dilutes focus.

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

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

It is complete enough for a live read tool with annotations and an output schema covering return values. The main remaining gap is that pid and project are left entirely to the schema, though their schema descriptions are already clear.

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 100%, so the schema already documents all six parameters. The description adds some meaning for start_line/end_line and surface_only, but much of that overlaps with schema descriptions, and its content_token mention does not map to an input parameter.

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

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

The description states a specific verb and resource: reading a module's text as the running editor holds it, including unsaved edits. It explicitly distinguishes this tool from xlide_read_module by explaining the exact difference is the user's unsaved work.

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 when-to-use guidance: use this to see what the user is actually working on, and use xlide_read_module for what is in the file. It also clarifies the surface_only condition and when that alternate read exists.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by framing it as a single read call, returning JSON, and deliberately limiting access to read routes only, which goes beyond the structured annotations.

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

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

Three sentences, each with a distinct job: statement of function, recommended first call, and route scope/exclusion. The route list is long but necessary because the schema lacks an enum, and no filler or redundant restatement appears.

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

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

With an output schema present and annotations covering side-effect safety, the description only needed to explain what the tool does, how to start, and which routes are valid—all provided. The only minor omission is behavior when a session isn't running, but the 'running session' qualifier and output schema make the tool callable without further documentation.

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 descriptions cover pid, query, and route at 100%, so baseline is 3. The description adds real value for route by enumerating all allowed routes and recommending the initial route value ('agent'), which is not present as an enum in the 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 'Calls one read route on a running xlide_vbide session and returns its JSON,' naming the verb, resource, and output format. It further differentiates by listing allowed read routes and explicitly excluding editor-driving routes, making the tool's scope unmistakable against sibling live-session tools.

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

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

It gives concrete usage guidance: 'Start with route="agent"' and lists allowed routes, plus states which routes are not reachable ('Routes that drive the editor are deliberately not reachable here'). It does not explicitly map to alternative sibling tools, but the exclusions and recommended starting point provide clear context for when this tool is appropriate.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description goes further by disclosing that each session is probed before listing and why: 'a discovery file outlives the process that wrote it.' It also adds platform and prerequisite context that the annotations do not express.

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

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

Three sentences, each earning its place: the main action and scope, the intended use case, then the platform/prerequisite and probing caveat. The most decision-relevant information is front-loaded in the first sentence.

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

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

For a zero-parameter tool with an output schema present, the description covers everything an agent needs: what the tool lists, how to interpret a session, when to call it, and operational caveats. There is no missing guidance that would prevent correct invocation or interpretation.

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

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

The input schema has no parameters and schema description coverage is 100%, so the baseline is 4. The description correctly emphasizes the tool's zero-parameter nature by focusing entirely on the output and invocation context rather than parameter details.

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: 'Lists the running xlide_vbide sessions this machine can reach,' and clarifies what counts as a session: one per Office process with the VBE open and add-in loaded. This distinguishes it from other xlide list tools, which target projects, modules, queries, or sheets.

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

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

The description explicitly states when to use it: 'Use it to find out whether the user has a live editor before asking about what is on their screen.' It also gives prerequisites (Windows only, add-in's local API must be switched on), but it does not name alternative tools or explicitly say when not to use it, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by detailing the live-state fields it reports, especially unsaved changes and break mode, which are not evident from annotations alone. No contradiction with annotations.

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

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

Two sentences: the first front-loads the essential state contents, the second gives clear usage guidance. Every sentence earns its place and there is no filler or repetition of schema/annotation content.

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

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

With a low-parameter count, complete schema coverage, rich annotations, and an output schema, the description supplies what remains necessary: when to use the tool and what state dimensions it covers. Nothing an agent needs to decide whether to invoke it is missing.

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

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

The sole parameter pid is fully documented in the schema with its default and behavior ('0 uses the only one, or refuses'), so schema coverage is 100%. The description does not add parameter-level meaning, but the baseline of 3 applies because the schema carries the full burden.

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

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

The description clearly defines the resource as the running Visual Basic Editor's live state and enumerates the exact contents: current module/project, break mode, unsaved edits, caret procedure, and analyzer status. This level of specificity distinguishes it from sibling tools like xlide_live_sessions, xlide_project_info, or xlide_read_module, which target different resources or scopes.

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

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

The description gives explicit use cases: when the user asks what they are looking at, or before suggesting an edit where unsaved changes may be relevant. It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough that an agent can route to 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?

Annotations declare destructiveHint=true and readOnlyHint=false, and the description usefully partitions behavior per action — 'list' changes nothing while 'set' replaces an existing note and 'remove' takes either kind off the cell. That per-action safety breakdown adds real context beyond the blanket annotation. It doesn't cover permissions, file-locking, or interaction with an open workbook, so not a 5.

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

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

Content is front-loaded: the first sentence gives the core verb/resource, and the following sentences explain the note-vs-thread distinction and the action semantics. It is on the longer side for one sentence of value, but every clause carries distinguishing information.

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

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

For an 11-parameter mutation tool with full schema coverage and an output schema, the description supplies the missing narrative: what each action does, which ones mutate, and which apply to threads only. Remaining gaps (pagination behavior, replacement/undo semantics beyond the note case) are minor.

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 100%, so the baseline is 3, but the description adds meaning the schema does not spell out — e.g. that 'reply' and 'resolve' only apply to threads, and that 'set' with kind='thread' starts a conversation. It stops short of explaining cell/offset/max_results semantics, which the schema already handles.

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

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

States specific verbs (lists, writes, answers, removes) against a specific resource (comments on a worksheet's cells), and explicitly disambiguates the two Excel comment kinds (note vs threaded comment). An agent can identify exactly what this tool does and how it differs from all siblings, none of which touch comments.

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?

Maps each action value to its effect ('list' reads both and changes nothing, 'set' writes/replaces, 'reply'/'resolve' act on a thread, 'remove' clears either kind off the cell) and gives a usage rule: 'Use a note to explain a cell to whoever reads the workbook next.' It does not name when another sibling would be preferred, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the semantic meaning of the 'differential format' (fill/font as the paint) and how expression formulas are applied relatively, but never states what 'clear' destroys or that clearing is irreversible, which matters for a destructive mutation tool.

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 three sentences are dense but front-loaded, leading with the action set and rule modes before the paint detail. Some phrasing (the aside about Excel's 'Use a formula' box) is explanatory padding that could be trimmed, keeping it below 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 14-parameter tool with full schema coverage, an output schema and destructive/idempotent annotations, the description covers the rule taxonomy and paint semantics well. It leaves the action (list/add/clear) contract and the destructive scope of 'clear' to the schema and annotations, so it is complete enough but not exhaustive.

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 100%, setting a baseline of 3, but the description genuinely adds meaning beyond it: it explains that rule='expression' takes a formula written for the range's top-left cell and applied relatively, and that fill/font are Excel's differential format. It does not touch the non-rule params (offset, max_results, other_value), so it falls short of 5.

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

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

The opening clause gives a specific verb set and resource ('Lists, adds or clears conditional formatting') and immediately disambiguates the concept ('the rules that colour cells by what is in them'), which separates it from static formatting siblings like xlide_format_cells. It does not name any sibling explicitly, so it stops short of a 5.

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 explains what each rule mode means ('cell_is' compares true, 'expression' takes a relative formula, 'color_scale'/'data_bar' are gradients/bars), which helps an agent pick a rule, but that selection is already surfaced in the schema's rule description. It gives no guidance on when to choose this tool over siblings such as xlide_format_cells, or when list vs add vs clear is appropriate.

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

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

Beyond the annotations (idempotentHint=true, destructiveHint=true), the description adds substantial behavioral detail: it hides filtered rows, it does not rely on Excel's in-memory filter state, 'list' is side-effect-free, 'set' preserves other filter conditions, and criteria follow VBA's Range.AutoFilter conventions. This gives an agent a realistic model of what the tool actually does and what side effects to expect.

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

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

The description is a dense single paragraph, but every sentence contributes real information: overall purpose, Excel's opaque filter-state behavior, per-action semantics, and criteria syntax. It could be improved with bullets for the action variantsainer, but the organization roughly follows the natural flow of actions and criteria, and nothing is wasteful.

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 12-parameter tool with an output schema and full schema descriptions, the description covers the key behavioral and selection details: which action to choose, how criteria map to VBA, and how filter state is computed. It does not explicitly walk through every edge case, such as what happens when no filter exists and 'reapply' is called, but the schema and output schema cover the remaining surface adequately.

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 already provides 100% coverage with per-parameter descriptions (criteria1, criteria2, top, dynamic, percent, etc.). The description adds meaningful context beyond that, especially the VBA Criteria1/Criteria2 spellings, examples like '=*east*', '=' for blanks, negative top for bottom N, and the note about calling 'set' once per column. This extra guidance is useful even with a well-documented 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 clear, specific verb+resource: 'Lists, sets, reapplies or clears the autofilter on a worksheet or on an Excel table'. It distinguishes the operation from filtering in general and from other worksheet/table management siblings. The four action variants are explicitly named.

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 usage context for each action: 'list reads the filters and changes nothing', 'set filters one column and keeps what the others already filter by; call it once per column', 'reapply filters again after the data changed', and 'clear removes the filter'. It also explains that Excel does not apply filters on open, so this tool is needed to compute visibility. It does not explicitly name sibling tools as alternatives, but the action-by-action guidance is clear enough for ordinary selection.

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

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

Annotations mark this destructive and non-readonly, and the description adds real context beyond them: it writes both designer storage and the code module, and explains that partial rename/delete would lose the form. It also surfaces the destructive consequence of saving and, via the schema, user-agreement gates for protected/signed projects.

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

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

Front-loaded with purpose, then rationale, then restrictions, then next steps – a logical order with no filler. Sentences are dense and somewhat long, but each carries distinct information, so only minor tightening is possible.

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

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

With annotations covering safety, a 100%-covered schema, and an output schema for returns, the description supplies everything else needed: scope, refusal conditions, the two-halves write model, and sibling routing.

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

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

Schema description coverage is 100%, so every parameter (width, design, new_name, allow_protected, etc.) is already documented with units and conditions. The description adds behavioral context around rename/delete but no per-parameter syntax beyond the schema, so the baseline 3 applies.

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

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

States specific verbs and resources ('Creates a UserForm, or an Access form or report, and saves the file') and distinguishes the three actions. It explicitly contrasts itself with sibling tools (xlide_write_module, xlide_edit_form), so an agent can tell it apart without opening schemas.

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

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

Names the exact contexts and constraints: rename/delete work only on Access designs where both halves move together, and are refused for UserForms. It routes follow-on work to xlide_edit_form (controls) and xlide_write_module (event procedures), covering when-to-use and when-not.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the mutation profile is partly covered. The description adds one genuine non-obvious behavior – the cell's displayed text is preserved unless 'display' is passed – but says nothing about whether add overwrites an existing link, whether remove is reversible, or the effect on cells outside cell_range.

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

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

Four short sentences, front-loaded with the verb/resource, then the branching rule, then the subtle display caveat. No filler and nothing buried.

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?

An output schema exists, so return values need no prose, and the description covers the three actions and the key parameter distinction. It is slightly thin for a 10-parameter, three-mode mutation tool in that it omits overwrite/reversibility semantics for add/remove.

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 100%, so per-parameter meaning is already documented and the baseline is 3. The description earns above baseline by explaining the relationship between 'target' and 'location' (external URL/file path vs intra-workbook reference) and clarifying that 'display' controls cell text independently of the link.

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 triple and resource: 'Lists, adds or removes hyperlinks on a worksheet.' The action vocabulary maps directly to sibling manage_* tools and an agent can distinguish it from manage_comment, manage_name, and manage_validation without reading further.

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 explains the target-vs-location mutual exclusivity ('Pass one or the other'), which is real usage guidance for the add case, but it never states when to choose list vs add vs remove or any prerequisites such as the file needing to be closed or the cell needing to exist.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real value: removing a name can break VBA code as well as formulas, and list is a no-op. That is exactly the kind of consequence detail annotations cannot convey.

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

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

Three sentences, front-loaded with the action scope, then the risk caveat, then the refers_to guidance. No filler, though the middle clause about VBA is slightly dense and could be tighter.

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

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

With an output schema present, return values need no explanation, and the description covers the destructive caveat and the non-obvious refers_to construction. Complete enough for a 7-param mutation tool, though permission/auth prerequisites are unstated.

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 100%, so baseline is 3, but the description meaningfully extends refers_to semantics beyond the schema's terse example by warning to qualify with the sheet and use absolute addresses to avoid active-sheet/copy drift. That adds meaning the schema does not.

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

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

States a specific verb set (lists/adds/removes) and resource (workbook defined names) in the first sentence, and it is clearly distinguishable from siblings like xlide_manage_reference or xlide_manage_table. An agent knows immediately what domain this touches.

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?

Clarifies the per-action semantics ('action=list changes nothing') and gives concrete guidance for constructing refers_to when adding a range. It does not explicitly name a sibling alternative or state when this tool should NOT be used, which keeps it short of a 5.

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

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

Goes well beyond the annotations by disclosing that the file is saved, that names resolve against the Windows registry, that ambiguous names are refused with candidates, and that adding the host's own library or removing Microsoft Forms while a UserForm exists fails. This is rich operational context an agent cannot get from readOnly/destructive hints alone.

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

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

Front-loaded with the core action and effect, then layers resolution and refusal rules. Dense but every sentence carries information; the long registry sentence is the only slightly heavy spot.

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?

An output schema exists, so return-value explanation is unnecessary. The description covers the mutation, platform variance, ambiguity handling, and refusal conditions, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: how the library string resolves (description, code name, or Excel/Word/PowerPoint/Access), where guid/version are needed, and that ambiguity is rejected. It enriches the schema rather than restating it.

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

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

States a precise verb pair (adds or removes) and resource (type library reference in a VBA project), plus the side effect of saving the file. This clearly distinguishes it from the sibling xlide_list_references, which only reads references.

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

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

Gives an explicit trigger ('Use it when xlide_analyze reports missing-library-reference, or when code needs early binding') and platform guidance ('Off Windows, pass guid and version'). It does not say when to avoid this tool in favor of another sibling, so it falls short of a full when/when-not/alternatives statement.

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?

Even though annotations already mark destructiveHint and readOnlyHint, the description adds essential behavior beyond them: formulas follow inserted rows, references into deleted cells become #REF!, deletion has no undo, and units are Excel-native. This is exactly the kind of contextual disclosure an agent needs.

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

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

Four sentences, each earning its place: the operation list, formula/reference consequences, undo warning, and unit/file-format context. Information is front-loaded and free of filler.

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

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

With an output schema, annotations, full parameter schema, and detailed behavioral notes, nothing essential is missing. The description covers safety (no undo), units, supported file formats, and Excel-compatible semantics, making it fully actionable.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description's mention of character/point units is valuable but duplicates the schema's parameter descriptions, adding no new parameter-level meaning.

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: 'Inserts, deletes, resizes, hides, shows, groups or ungroups whole rows or columns.' This fully enumerates the tool's scope and clearly differentiates it from sibling tools like manage_sheet or manage_table, which operate on different resources.

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 usage context is explicit: any row/column structure manipulation belongs herecing, not implied. However, it doesn't name alternatives or state when not to use this tool, so it stops short of the highest bar.

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

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

The description discloses several behaviors beyond annotations: it saves the workbook, leaves the macro when a shape is removed, requires the four parts of a Forms control to agree, and restricts to Excel workbook types (.xlsx, .xlsm, .xlam). Annotations already mark it as destructive and readOnly=false, but the description adds concrete side-effect details that are essential for safe use. No contradiction with annotations.

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

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

The description is dense but well-organized, starting with the general action, then the typical use case, placement rules, specific kind requirements, and caveats. Every sentence adds value, though it is longer than strictly necessary. It is front-loaded with the main purpose and key constraints, making it effective despite its length.

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

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

Given the tool's complexity (16 parameters, multiple kinds, interlocking rules), the description covers the essential calling context: common patterns, placement semantics, parameter dependencies, side effects (saves workbook, leaves macro), and limitations (no chart removal, Excel-only). An output schema exists, so return values are not expected here. The description is thorough 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.

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

Even though the schema covers 100% of parameters, the description adds crucial inter-parameter relationships: how kind='button' pairs with text and macro, how cell relates to left/top and width/height defaults, and that linked_cell/list_range apply to specific kinds. This goes well beyond the individual schema descriptions, clarifying when each parameter is relevant.

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 (adds/removes) with a clear resource (shapes, controls, etc.), and explicitly excludes charts ('removing a chart is not offered'), which distinguishes it from sibling xlide_add_chart. It also clarifies it saves the workbook, which is a distinct side effect. The purpose is 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 provides rich usage context: the common button+macro pattern, placement options (cell vs. left/top), and which kinds require linked_cell or list_range. It also gives an explicit exclusion ('removing a chart is not offered'). However, it doesn't directly name sibling tools like xlide_list_shapes or xlide_set_shape_macro as alternatives for related tasks, leaving some routing to inference.

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

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

The description goes well beyond the annotations by disclosing that renaming rewrites formulas and defined names, that removal is irreversible and breaks external references with #REF!, and that sheet protection is only obfuscation with easily recovered passwords. This is exactly the behavioral context an agent needs for a destructive, state-changing tool.

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

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

The description is well-organized: operation list first, then action-specific consequences, then supported formats. Every sentence adds meaningful information, and there is no filler or repetition of the schema's parameter names.

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

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

Given the tool's complexity — seven parameters and eight possible actions — the description covers the critical edge cases: irreversible removal, formula rewriting on rename, Excel protection caveats, and file format compatibility. The output schema exists, so return-value details are not required in the description.

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

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

The schema already documents all 7 parameters with descriptions and defaults, so the baseline is 3. The description adds value by enumerating the exact allowed values for the action parameter (add, remove, rename, move, hide, show, protect, unprotect) and by explaining the consequences that distinguish one action from another.

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 set of verbs and a clear resource: 'Adds, removes, renames, moves, hides, shows, protects or unprotects a worksheet.' This fully disambiguates it from sibling tools that read or edit other workbook parts, and the title reinforces the same scope.

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 makes the tool's worksheet-level scope clear and includes a strong 'ask the user first' directive for removal. However, it does not explicitly name alternatives or state when NOT to use this tool versus sibling tools like xlide_manage_rows_columns or xlide_manage_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?

Annotations declare destructiveHint=true and readOnlyHint=false, and the description earns its keep by explaining the actual damage: 'Removing one leaves the cells and takes the table, so structured references to it break.' That is materially useful beyond the hint, though it doesn't cover auth/file-lock or errors.

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

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

Front-loaded with the action set, then uses the remaining space for genuinely informative context on tables and the destructive remove behavior. The middle sentence about Power Query is slightly tangential but still short and relevant.

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?

An output schema exists and annotations cover the safety profile, so the description does not need to explain returns. It fills the remaining gaps well: the semantic meaning of a table, per-action effects, and the consequence of removal. Minor absence of pagination context given max_results/offset params.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the 'For list/add/remove' prefixes. The description reinforces that add derives column names from the header row of cell_range, but adds no syntax or format detail beyond the schema's own 'A1:D20' example, so the baseline 3 applies.

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

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

Opens with a specific verb set and resource ('Lists, adds or removes Excel tables, the ListObjects'), and immediately grounds it in a concrete concept (Ctrl+T blocks, structured references). It is unmistakably distinct from siblings like xlide_manage_reference or xlide_manage_name.

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?

Explains what each action does and its side effects: 'action=list reads them and changes nothing', add takes column names from the header row, remove leaves the cells. There is clear contextual guidance, though it never names an alternative tool or states explicit when-not-to-use conditions.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds genuinely non-obvious behavior: validation gates typing in Excel and does not apply to writes made through this server, and pre-existing cell values are not re-validated. It does not address permissions, but this is meaningful value beyond the annotations.

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

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

Three dense sentences, no filler, and the critical behavioral caveat is placed last but still earns its space. Slightly heavy on formula semantics for a description, but nothing is wasted.

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 12-parameter mutation tool with an output schema, the description covers the semantically tricky parts (kind/formula combination and the Excel-side enforcement limit) while the schema and output schema carry the rest. Nothing an agent needs to invoke it correctly appears 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?

With 100% schema description coverage the baseline is 3, and the description earns above it by explaining the two distinct formula1 modes for kind='list' (comma-separated literal set vs. range reference) and the operator/one-or-two-formula pattern for other kinds. It leaves offset, max_results, allow_blank, and error_message to the 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?

Front-loads a precise verb triad (lists/adds/clears) with a specific resource (data validation), then immediately clarifies scope with 'what a cell will accept, and the dropdown it shows.' This is distinguishable from siblings like xlide_manage_conditional_format or xlide_check_cells without opening a schema.

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

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

The description explains the semantics of the kind parameter (how list vs. operator-based kinds behave) but never states when this tool is the right choice over adjacent tools like conditional formatting or cell checking, nor any prerequisites. Usage is implied by the parameter walkthrough rather than asserted.

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

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

Annotations are all negative hints (false), giving no behavioral information. The description carries the full burden and does so thoroughly: it details the effect of read_only (a copy that cannot be saved over), new_instance (separate Excel/Word without other files), bring_to_front=false (reopens behind), macro handling per Trust Center, and the Windows-only limitation. This is substantial value beyond the annotations.

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

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

The description is four sentences, each carrying distinct meaning: purpose, already-open behavior, parameter effects, and macro/platform constraints. It front-loads the core purpose and keeps every sentence relevant without redundancy.

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

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

For a tool with 4 parameters, an output schema, and no positive annotations, the description covers all essential aspects: purpose, behavioral nuances, parameter effects, macro security, and platform limitation. It references the complementary sibling tool and explains edge cases. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% with already descriptive parameter text. The description adds extra nuance: it explains read_only as 'a copy that cannot be saved over the file' (similar), but notably clarifies new_instance as a separate app 'the user's other files are not in', which deepens the schema's 'rather than the one running'. It also clarifies bring_to_front=false as 'reopens it behind whatever the user is doing', adding practical meaning.

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