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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description's 'Lists' wording is consistent with all of them. The description adds useful context about the Access file type and the relationship between code and schema, but no additional operational behavior such as auth or system-table filtering, which is acceptable given the strong 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?

The description is three sentences: a concrete front-loaded scope, a brief rationale for why the tool matters, and a crisp scope constraint. Every sentence earns its place, and there is no repetition of schema 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?

With an output schema present, full parameter documentation, and safety annotations, the description covers the remaining contextual needs: what the tool returns conceptually, why it exists, and that it applies only to Access files. An agent has enough information to invoke it correctly with just file_path and optional filters.

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 the schema already documents file_path, include, and include_system in detail, so the baseline is 3. The description reinforces the meaning of include by naming tables, queries, and relationships, but it adds no new parameter-level semantics or formatting 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?

The description uses a specific verb ('Lists'), names the resource ('an Access database'), and spells out the concrete output categories: tables with columns, saved queries with SQL, and relationships. It clearly positions the tool as a schema catalog rather than a code-reading tool, distinguishing it from siblings like xlide_list_modules and xlide_read_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?

The description explains why this tool is needed in a real workflow: an .accdb is an application, its VBA is written against tables/queries, and reading modules alone would only show half of it. It also gives a clear boundary with 'Access files only.' It stops short of naming a specific sibling alternative, so it does not quite earn 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?

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description adds valuable behavioral context: no Office installation, no code execution, and host-specific object-model judging. These details materially inform an agent about side effects, environment requirements, and analysis semantics.

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?

Five dense sentences deliver the core operation, execution constraints, host-model nuance, and an actionable severity policy. There is no filler, repetition, or fluff; every sentence earns its place.

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

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

An output schema exists, so the return shape is already covered. The description supplies the remaining operational context an agent needs: safety, non-execution, host coupling, and the error-as-build-failure policy. This is complete for an agent deciding to invoke the 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 description coverage is 100%, so file_path, module_name, and min_severity are already fully documented in the schema. The description adds no parameter-level detail beyond the general scope 'every VBA module', so the 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?

The description opens with a specific verb and resource: 'Runs static analysis over every VBA module in an Office file', and enumerates the returned problem fields (module, line, column, code, message). It also differentiates itself from execution/run tools by stating it 'runs nothing' and needs no Office installation.

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

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

It gives an explicit when-to-use instruction: 'Call this after every VBA change and treat any problem at error severity as a build failure'. This provides clear context and policy, but it does not explicitly name alternatives or state when not to use it versus tools like xlide_compile_check or xlide_validate_project, so it falls just short of a 5.

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

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

The description discloses key behavioral traits beyond annotations: it is static, costs nothing, needs no file, and catches compile errors. It also explains how file_path alters behavior by resolving calls into the project. While annotations already indicate read-only and idempotent, the description adds context about the analysis scope and parameter effects. It does not mention return format, but an output schema exists, so that is covered.

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 three sentences, front-loaded with the core purpose, followed by usage guidance. Every sentence adds value without redundancy or fluff. It efficiently communicates the tool's role and key parameter decisions.

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 moderate complexity, an output schema, and comprehensive annotations, the description covers all essential aspects: what it does, when to use it, how to parameterize it, and its cost-free non-destructive nature. The agent has sufficient information to decide when to use this tool and how to construct valid calls.

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 each parameter has a description. The tool description adds extra meaning for host and file_path, explaining their purpose and how they affect analysis. For other parameters (source, kind, module_name), the schema descriptions suffice. This added context elevates the score above the baseline of 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 clearly states the tool's function: 'Runs static analysis over VBA source you are holding, before it is written to a file.' It identifies the specific verb (analyze), resource (VBA source), and context (pre-write). It distinguishes itself from siblings by emphasizing it operates on in-memory source ('needs no file'), making its purpose unambiguous.

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

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

The description explicitly states when to use the tool: 'Use it to check code you have just generated.' It also provides concrete guidance on parameter selection: 'Pass host so the code is measured against the right object model, and file_path instead if the code is destined for a file that already exists.' This gives the agent clear instructions on when and how to invoke it, covering both usage timing and parameter differentiation.

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 only carry negative hints (readOnly=false, destructive=false, idempotent=false), so the description carries the behavioral burden. It discloses the template origin and the no-repair-promise, the extension-specific behavior for .xlsx, and the no-overwrite guarantee. It doesn't state what happens on conflict or directory creation, but the key behaviors are covered.

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: purpose first, then supported formats, then the no-overwrite behavior. No fluff, no repetition of schema details.

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

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

Given a single parameter, an existing output schema, and a clear purpose, the description covers everything an agent needs: what is created, how to specify the path, which extensions are valid, and the critical no-overwrite constraint.

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 already explains 'absolute path' and 'extension picks the format.' The description adds value by enumerating the supported extensions, which clarifies valid values for file_path beyond the schema's generic statement.

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 ('Creates'), a specific resource ('new Office file with an empty VBA project'), and important distinguishing details (template authored by the app, no repair prompt, never overwrites). This clearly separates it from the many read/write/modify siblings.

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 use case is clear: create a new Office file at an absolute path. It also gives an implicit exclusion ('never overwrites an existing file'), telling the agent not to use it when the file already exists. It doesn't explicitly name alternative tools, but no sibling performs creation, so none is needed.

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 explaining that deletion is permanent, that there is no undo, that the user must be asked first, and that the module should be read beforehand so its code can be restored. This is strong behavioral disclosure for a destructive action.

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 short sentences deliver the core action, the irreversible risk, and the required safety workflow without waste. The destructive nature is front-loaded, making the tool's risk profile immediately visible.

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

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

The annotations cover destructiveness, the schema fully describes all five parameters, and an output schema is present. The description supplies the missing behavioral context: irreversibility, user confirmation, and the document-module restriction. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the input schema already explains all parameters. The description's 'read the module before deleting' guidance aligns with expected_content_token but does not add detailed parameter-level meaning beyond the schema. 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?

The description states a specific verb and resource: 'Permanently deletes a VBA module from an Office file and saves it.' This clearly distinguishes the tool from sibling operations like rename, write, or read, and the permanence is stated up front.

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

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

The description gives explicit procedural guidance: ask the user first, read the module before deleting, and warns that document modules cannot be deleted. It does not name alternative tools, but it clearly communicates the required preconditions and a key exclusion.

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?

Beyond annotations (destructiveHint=true), the description discloses concrete destructive behavior: 'Removing a container takes its children with it'. It also reveals that setting a property to null resets the control to default, and that adding a control does not write its event procedure. These details materially explain side effects not captured in 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 5 sentences, front-loaded with the core operation and immediately followed by high-value clarifications (units, null, cascade, event procedures). Every sentence earns its place, and there is no repetition of schema details already 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?

Given 16 parameters and a destructive annotation, the description covers the main risk points (container removal, null semantics, event procedure omission) and clarifies units. An output schema is present, so return values are already documented. The description is sufficient for correct invocation without additional exploration.

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 coverage, the schema already describes all 16 parameters individually. The description adds cross-cutting semantics: unit types (points vs twips) for geometry parameters, the null-clears-default behavior for property_value, and the container-cascade note affecting control_name and action. This meaningfully supplements the parameter descriptions.

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: 'Changes one form's design and saves the file' and enumerates three precise operations (add a control, remove one, set a property). This clearly distinguishes it from siblings like xlide_read_form (read-only) and xlide_manage_form (likely broader management), and the scope is explicit ('one form').

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 includes a clear alternative for event procedures ('do that with xlide_write_module on the form's code module') and instructs to ask the user before removing a container. It also clarifies unit differences (points vs twips) which guide input. However, it does not explicitly say when not to use this tool versus other edit-like siblings (e.g., xlide_manage_form), leaving some inference to the agent.

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, and the description adds crucial context: the preview-by-default behavior, the apply flag gate, the copy semantics (editing exported files does not affect the Office file), and the delete_stale user-consent requirement. This goes beyond the annotations and clarifies the destructive risk.

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, all information-dense and front-loaded with the core action, then the preview default, then the copy semantics. No filler or repetition of schema details.

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

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

The description covers the key behavioral aspects an agent needs: default preview, apply gate, delete_stale consent, and the relationship to xlide_import_modules. It doesn't describe the output schema's return values, but an output schema exists, so that burden is lifted. Minor gap: it doesn't state what happens if the export folder is invalid or the file is locked, but that's not essential 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 all four parameters. The description adds context for apply (preview vs write) and delete_stale (ask user first), but it doesn't add much beyond the schema's own descriptions. 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?

The description states a specific verb ('Writes'), a clear resource ('every VBA module in an Office file'), and the output format ('.bas and .cls files'), which distinguishes it from sibling tools like xlide_read_module or xlide_import_modules. It also names the inverse operation (xlide_import_modules) and the source-control/review purpose, so an agent can tell exactly what this tool does.

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 says it previews by default and writes nothing until apply=true, and it names the complementary tool xlide_import_modules as the way changes get back into the Office file. It also mentions delete_stale requires asking the user first, giving clear when-to-use and when-not-to-use 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?

Building on annotations, the description adds valuable behavior: partial updates preserve untouched formatting ('making a header row bold does not flatten the number formats under it'). It also discloses color syntax rules and that the number format code determines date display. It does not contradict the idempotent/destructive hints, though it could have warned about merge data loss itself.

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 with no filler: the operation is front-loaded, the most important behavioral nuance follows, and supporting conventions (colors, number format codes, file types) are packed efficiently at the end.

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 18-parameter tool, the description covers the operation categories, partial-update behavior, color and number-format conventions, and supported file types. The parameter schema and output schema already carry the remaining details, so nothing critical is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-cutting meaning: hex colors must omit the leading hash, and number_format is an Excel code that also controls date rendering. This is useful shared semantics that apply to several parameters and is not obvious from individual schema descriptions.

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 ('Changes how a range looks') and enumerates the exact formatting operations it covers. This clearly separates it from value-editing siblings like xlide_write_cells by emphasizing appearance, not cell content.

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 intended use is implied by the listed formatting operations and the explicit statement that only passed properties are modified, but it never states when to choose this tool over alternatives such as xlide_manage_conditional_format or xlide_manage_sheet. There is no explicit exclusion or when-not-to-use 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 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?

The description adds substantial behavior beyond the annotations: preview-by-default, no writes until apply=true, automatic creation for unmatched filenames, and the rule that document modules are written but never created. This meaningfully informs an agent about side effects before invocation.

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 core action, followed by the most important behavioral nuance and edge cases. No filler or redundant repetition of schema fields; every sentence earns its place.

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

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

The description covers the core operation, default preview behavior, creation rules, and a follow-up action. The only notable gap is that it never states what happens to existing modules that have no corresponding file in the source folder, which is relevant given destructiveHint=true.

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 does not add parameter-level detail beyond restating the apply/preview behavior already present in the schema, which meets the baseline but does not exceed 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?

The description states a specific verb ('reads... back into') and resource ('an Office file's VBA project'), making the tool's purpose unmistakable. It also distinguishes itself from siblings like xlide_export_modules by signaling the reverse direction of data flow.

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

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

The description clearly implies the primary use case: batch-importing .bas/.cls files from a folder into a VBA project. It gives workflow guidance ('After applying, call xlide_analyze') but does not explicitly name alternatives such as xlide_write_module, nor state when not to use this tool.

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 known. The description adds valuable context beyond annotations: it specifies that the output includes control counts and, for Access, the sections a control can go in, and it clarifies that the design's code is a separate module. No contradictions 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 concise at two sentences, front-loads the primary action, and includes a useful pointer to the related module-reading tool. Every sentence earns its place with no filler or redundancy.

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

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

For a simple tool with one parameter and an output schema, the description is complete. It explains what is listed, the extra details provided, and the relationship to code modules. The annotations cover safety, so nothing essential is missing for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with a clear description for file_path ('Absolute path to the Office file'). The description adds meaning by clarifying that the tool also handles Access databases, which is not explicit in the schema's 'Office file' phrasing. This enriches the parameter semantics 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?

The description clearly states the action: lists UserForms in Office files or forms and reports in Access databases, with specifics like control counts and sections. It distinguishes this from sibling listing tools by naming the resource type (forms/reports) and the follow-up tool (xlide_read_module) for reading the associated code 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?

It implies usage by defining the tool's scope (Office vs. Access) and mentions a companion tool (xlide_read_module) for reading the design's code. However, it does not explicitly state when not to use it or contrast it with similar listing tools like xlide_list_modules or xlide_read_form. The context is clear but lacks explicit exclusions.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, covering the safety profile. The description adds useful context by explaining that the returned content_token is meant to be passed to a guarded write, which goes beyond what annotations or a bare schema would say.

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 two sentences long, front-loads the tool's purpose and output, and avoids irrelevant details. Every sentence contributes either to what the tool returns or to when it should be selected.

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

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

For a simple one-parameter read-only tool with a full output schema and embedded annotations, the description covers the necessary context: what is listed, the file scope, and the routing to an alternative. Nothing critical is missing for an agent to call it appropriately.

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 one required parameter and 100% schema description coverage, the schema already explains file_path as an absolute path. The description does not add new parameter-level meaning, so it stays at the baseline of 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 states a specific verb and resource: 'Lists the VBA modules in an Office file,' with concrete output fields like kind, line count, and content_token. It also distinguishes itself from xlide_project_info, making the tool's role 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?

It explicitly names the alternative xlide_project_info and gives the condition for choosing this tool: 'use this one when the file is already known and only the file is already known and only the module list is wanted.' This tells an agent exactly when to use it and when a more complete sibling is preferable.

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, covering the safety profile. The description adds context by clarifying that the tool focuses on a single module and returns declaration-level metadata, which helps set expectations 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?

The description is two sentences: the first states exactly what is listed, and the second provides a practical use case. There is no filler, and the core behavior is front-loaded ahead of the guidance.

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

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

The tool has only 2 required parameters, both fully described by the schema, an output schema exists, and annotations already cover the safety model. The description adds the key intent and scope (single module, change-locating) with nothing essential 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 both file_path and module_name are already documented in the schema. The description only adds the concept of 'one module', which aligns with module_name but does not materially extend the meaning of the parameters.

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

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

The description uses a specific verb 'Lists' with a precise resource: 'the Sub, Function and Property procedures in one module'. It also enumerates the returned attributes (kind, scope, line number, signature), which clearly differentiates it from sibling tools like xlide_list_modules that list modules rather than procedures.

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 a concrete use case: 'Use it to find where to change something without reading a long module in full.' This tells the agent when the tool is valuable, though it does not explicitly name alternatives or state when not to use it, 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?

Annotations already declare readOnly and idempotent hints, so the description does not need to repeat safety details. It adds useful behavior beyond annotations by documenting the exact file coverage and the important edge case that recognized-but-unopenable files are listed with reasons, preventing silent omissions.

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?

Every sentence earns its place: purpose and return values, usage guidance, supported formats, and a missing-file behavior guarantee. The information is dense but well-organized and front-loaded with the primary action and result.

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 listing tool with one optional parameter and an output schema, the description is complete. It covers what is returned, which file types are relevant, how subfolder scoping works, and the behavior for unopenable files, so an agent has everything needed to call and interpret the result.

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

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

There is only one parameter, subfolder, and the input schema already describes it completely, including the empty-means-everything semantics. The tool description does not add further parameter-level meaning, 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 clearly states the tool finds Office files in the workspace and returns their absolute paths, host application, and VBA openability. The extensive extension list removes ambiguity about what counts as a project, and the explicit 'Call this first when the user has not named a file' distinguishes it from named-file tools.

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

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

The description gives a clear usage directive: call this first when the user has not named a file. It does not explicitly name sibling alternatives for the named-file case, so it stops short of full when/when-not guidance, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuine behavioral context by noting that Power Query queries live outside the VBA project and exist even in plain .xlsx files, which is not derivable from annotations or 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?

Three tight sentences, each earning its place: the first defines the operation and outputs, the second adds a non-obvious fact about query storage, and the third gives a practical invocation cue. No redundancy or 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 a single fully documented parameter, rich annotations, and an output schema present, the description supplies all additional context an agent needs: what is listed, where the data lives, and when to call it. Nothing important 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%, and the single parameter file_path is already documented as the absolute path to the workbook. The description adds no parameter-level meaning beyond that, 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?

The description states a specific verb and resource: it lists Power Query queries in an Excel workbook and enumerates the exact attributes returned (name, group, description, load destinations, applied step names). This clearly distinguishes it from sibling list tools like xlide_list_modules or xlide_read_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?

The description explicitly gives a usage context: call this when asked what a workbook does, including workbooks without macros. It stops short of naming when-not-to-use or alternative tools, so it is clear but not fully 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?

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains that the tool lists shapes across all sheets when sheet is empty, that ActiveX controls are listed but have no macro, and that OnAction names are not rewritten by anything. This gives the agent a clear picture of what the tool will and won't return.

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 with zero waste. The main purpose is front-loaded, the shape types are enumerated compactly, and the usage guidance is woven in naturally. Every sentence earns its place: purpose, when-to-use, and a caveat about ActiveX controls.

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

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

The tool has an output schema, so return values don't need to be described. The description covers the main behavioral aspects: what is listed, the sheet scoping, the macro association, and the ActiveX caveat. It could mention whether the tool requires the file to be open or whether it opens it, but given the output schema and annotations, this is a minor gap.

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 both parameters. The description adds context about the 'sheet' parameter's behavior ('Empty lists every sheet's shapes') and implies the file_path is an absolute path, but it doesn't add much beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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 ('Lists') and a precise resource ('what sits on a worksheet's drawing layer'), enumerating the shape types and the two key data points (covered cells, macro on click). It clearly distinguishes itself from sibling tools like xlide_list_sheets (which lists worksheets) and xlide_list_procedures (which lists VBA procedures), so an agent can tell them 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?

The description gives explicit when-to-use guidance: 'Call it when asked how a workbook is started, or before renaming a Sub: a button's OnAction names a procedure and nothing rewrites it.' This tells the agent the exact scenarios and explains why the tool is needed. It also notes the ActiveX limitation, which implicitly tells the agent not to expect macro names for ActiveX controls.

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 annotations already establish read-only, idempotent, non-destructive behavior, and the description adds valuable non-obvious behavior: it surfaces used ranges and named ranges, and discloses the binary-format limitation. This tells the agent upfront why a request may fail on older workbook formats.

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

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

Three compact sentences front-load the core purpose, then provide a usage directive and a format compatibility warning. There is no filler or repetition of schema 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 listing tool with a rich output schema already present, the description covers everything the agent needs to decide when to call it and what to expect. The missing return-value details are supplied by the output schema, so nothing essential is absent.

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%: file_path is documented as an absolute path and timeout as seconds for Excel to answer. The description does not need to repeat these details, but it also does not add extra parameter semantics 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?

The description states a specific verb ('Lists') and a concrete resource ('worksheets in an Excel file'), then enumerates the returned details: used ranges, hidden status, and named ranges. This clearly distinguishes it from sibling listing tools like xlide_list_forms and xlide_list_procedures.

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

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

It gives an explicit when-to-use instruction ('Call this before reading cells') and explains why, so the agent knows it is the prerequisite discovery step for cell reads. It also names exclusion criteria by listing supported extensions and explicitly stating that .xlsb/.xls files are not readable by this server.

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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: it reads unsaved editor state, can differ from the file-based read, and surface_only only works for modules open in a tab. This is exactly the kind of non-obvious behavior an agent needs to know.

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

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

Three sentences with no wasted words. The most important behavioral fact (unsaved edits) is front-loaded, the sibling distinction comes second, and the parameter nuance is placed last. Every sentence earns its place.

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

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

Given the output schema exists and annotations cover safety, the description provides the remaining context an agent needs: when the result differs from xlide_read_module, when to choose this tool, and the caveat about surface_only. This is complete for an agent to 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 the baseline is 3. The description adds value by clarifying the conceptual difference between reading through the editor and reading the modern editor's own copy, especially tying surface_only to open-tab availability. It does not deeply elaborate on pid/project, but the schema already documents those adequately.

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 verb and resource: 'Reads a module's text as the running editor holds it'. It also immediately differentiates this tool from xlide_read_module by identifying the exact difference (unsaved edits), so an agent can select it correctly without needing to inspect sibling 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?

Usage guidance is explicit: use this tool to see what the user is actually working on, and use xlide_read_module for what is in the file. The description also explains the surface_only parameter's conditional availability, telling the agent when it can and 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 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 already signal non-read-only, destructive, and idempotent behavior; the description adds meaningful behavior beyond that by explaining how rule types behave: cell_is compares values, expression formulas are applied relatively from the top-left cell, and color_scale/data_bar are gradient and in-cell bar formats. This gives the agent a mental model of the mutation's semantics rather than only its safety profile.

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 two dense sentences with no filler. It front-loads the primary action, then systematically explains each rule type in an efficient, readable progression. Every sentence contributes necessary semantics.

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 12-parameter complexity, the schema's 100% coverage, and the presence of an output schema, the description supplies the missing conceptual glue: what each rule mode means and how fill/font relate to Excel's differential formats. It does not fully map every parameter combination per action, but it gives enough orientation for an agent to use the schema confidently.

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?

Although schema coverage is 100%, the description elevates the parameters by providing the conceptual framework: 'rule', 'operator', 'value', 'formula', 'fill_color', and 'font_color' are tied to actual Excel conditional-formatting behavior. It adds meaning beyond the terse schema field descriptions, such as the relative-formula semantics of 'expression' and the 'differential format' notion for fill/font.

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

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

The description opens with a specific verb-resource pair — 'Lists, adds or clears conditional formatting' — and then defines exactly what conditional formatting is: rules that colour cells by their contents. It clearly separates this from sibling formatting tools like xlide_format_cells by focusing on rule-driven, condition-based formatting.

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 domain unmistakable: use it whenever conditional formatting rules need to be listed, added, or cleared. It does not explicitly name alternatives or say when not to use it, but the context is clear enough that an agent can route to this tool without confusing it with static formatting or validation siblings.

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 beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) by explaining that a form consists of both designer storage and a code module, that this tool writes both, and that performing only half of a rename/delete would lose the form. This is concrete behavioral context that an agent needs and is consistent with 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 sentences, each carrying unique information: the core action, the rationale vs. sibling tools, and the operational constraint with follow-up tools. It 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?

The core behavior, the two-part form structure, the refusal condition for UserForms, and next steps (xlide_edit_form, xlide_write_module) are all covered. The allow_protected and allow_invalidate_signature parameters are not addressed, but they are documented in the schema, and an output schema exists, so this is only a minor gap for 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 coverage is 100%, so the baseline is 3. The description adds some context around action-dependent behavior (e.g., rename/delete refused for UserForms) and the split nature of forms, but it does not add per-parameter details beyond the schema, which already documents defaults and units for width/height.

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: 'Creates a UserForm, or an Access form or report, and saves the file.' It also covers rename and delete semantics, and explicitly differentiates itself from xlide_write_module by explaining the two-part storage model. The title is equally informative.

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 names alternatives explicitly: 'which is why it exists rather than xlide_write_module', and 'Add controls afterwards with xlide_edit_form, and write its event procedures with xlide_write_module.' It also states when the tool refuses operations (UserForm rename/delete), so an agent knows when not 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?

Annotations already signal mutability, destructiveness, and idempotence. The description adds useful behavioral context beyond that: the distinction between target and location, and the fact that displayed cell text is preserved unless 'display' is explicitly provided. This materially helps an agent predict side effects.

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

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

Four sentences, each earning its place: the action scope, the two link kinds, the mutual-exclusion rule, and the display-text caveat. No filler or repetition of schema details.

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

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

Given an output schema, full parameter descriptions, and annotations, the description covers the key relationships an agent needs to call the tool correctly. It could be more explicit about action-specific required parameters, but the schema already documents those per-action notes.

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 beyond the schema by explaining the target/location mutual exclusivity and the independence of display text, which are not encoded in the individual parameter descriptions.

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, adds or removes hyperlinks on a worksheet.' This clearly distinguishes it from the many sibling manage_* tools, none of which target hyperlinks.

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

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

The description gives clear operational context, explaining that a hyperlink can be external or internal and instructing to 'Pass one or the other.' It does not explicitly name alternatives, but no sibling tool covers hyperlinks, so the usage context is sufficiently clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds valuable nuance by explaining that mutating names can break VBA code and formulas, and by explicitly flagging that the list action is side-effect-free. 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?

Three tightly written sentences: the first states function, the second provides necessary risk context, and the third gives actionable parameter guidance. Every sentence earns its place and key material is front-loaded.

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

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

Given that the input schema documents all parameters and an output schema exists, the description covers everything an agent needs: what the tool does, when list is safe, why mutations are risky, and how to construct a valid refers_to argument. No critical gaps remain.

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 practical meaning beyond the schema by explaining that refers_to must contain sheet names and dollar signs (Data!$A$1:$A$50) and by clarifying the behavioral difference of the action='list' value.

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?

Clearly states the resource (workbook defined names) and the exact actions (lists, adds, removes). The TaxRate example makes the concept immediately recognizable and distinguishes this tool from sibling sheet/cell/module 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?

Provides clear context on safe usage ('action='list' changes nothing') and on how to format refers_to, which is essential for calling the tool correctly. It does not explicitly name alternatives or exclusions, but no competing sibling tool exists for this specific resource.

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 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 already declare readOnlyHint=false and destructiveHint=true, and the description adds materially: list is read-only, adding derives column names from the header row, and removing leaves the cells intact while breaking structured references. This discloses the real consequence of deletion beyond the boolean hint.

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 operation and entity, and each sentence adds a distinct piece: definition, rationale, action semantics, and removal side effect. The formula/Power Query background is slightly expository but remains relevant and concise.

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

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

For a three-action tool with six parameters, the description plus annotated schema covers prerequisites (header row for add, empty sheet meaning all tables), side effects (structured references break), and read-only list behavior. The output schema covers return values, so nothing needed for correct invocation 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?

All six parameters are fully documented in the input schema, so the baseline is 3. The description adds value by linking action values to parameter roles: cell_range must include the header row, and table_name is used for add and remove while preserving cells. This supplements the schema without redundancy.

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 pair: 'Lists, adds or removes Excel tables' and identifies the entity as 'the ListObjects that Ctrl+T creates.' This clearly distinguishes Excel tables from sheets, names, or modules handled by sibling tools.

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

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

The description gives clear contextual signals for when the tool is relevant, noting that tables are what Power Query loads write into and that action='list' reads and changes nothing. It does not name alternative sibling tools explicitly, so it stops short of full when-to-use-versus-alternative guidance.

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

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

Annotations already mark this as destructive and not read-only. The description adds valuable behavior beyond annotations: validation is not enforced by the server, and Excel will not re-check cells that already contained a value. This is exactly the kind of side-effect nuance 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?

The description is front-loaded with the core purpose and every sentence earns its place by explaining selection behavior, formula semantics, or the server/Excel distinction. It is slightly dense but not bloated.

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, the 100%-covered schema, and the presence of an output schema plus annotations, the description is complete. It covers the action variety, dropdown semantics, non-list kinds, and the key Excel/server behavior without needing to restate parameter catalogs or return formats.

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 adds extra meaning by explaining that kind='list' with comma-separated formula1 produces a dropdown, while a range reference drives it from cells, and other kinds rely on operator plus formulas. This clarifies relationships between parameters 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?

The description names a specific resource (data validation) and the exact verbs 'Lists, adds or clears', immediately distinguishing it from sibling tools like xlide_manage_conditional_format and xlide_manage_hyperlink. It also clarifies the dropdown behavior, leaving no ambiguity about what the tool operates on.

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

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

The description gives clear context for when to use data validation and provides internal guidance on choosing kind='list' with inline values versus a range, plus the operator/formula pattern for other kinds. It does not explicitly name alternatives, but the resource focus makes the tool choice clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description confirms the read-only nature and lists the read scope, but adds no further behavioral details such as output format, failure modes, or side effects. 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 purposeful sentences: the first defines the read scope with concrete examples, and the second gives usage context. There is no filler or repetition of schema details, making it appropriately efficient.

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

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

For a simple read-only tool with only two fully documented parameters and an output schema present, the description is complete. It states what is read, when to call it, and the safety profile is covered by annotations. No essential information is missing for an agent 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%: both file_path and sheet have clear descriptions in the input schema. The description does not add additional parameter meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description begins with a specific verb and resource: 'Reads how a worksheet is set up to print' and then enumerates exactly which aspects are read. This clearly distinguishes it from sibling tools like xlide_read_cells or xlide_manage_sheet by narrowing the scope to print settings only.

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 second sentence gives explicit trigger conditions: 'Call it when asked why a sheet prints the way it does, or before changing a layout somebody set up deliberately.' This is clear context for when to use the tool, though it does not mention when-not-to-use or name alternative tools.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context beyond that: it reports password/signing status and notes that each module carries a content_token for a guarded write, which is exactly the kind of behavioral detail an agent needs when planning follow-up actions.

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 accomplish the full job: the first states the aggregate scope and its contents, the second gives explicit usage timing and the token behavior. Everything earns its place and the key instruction is front-loaded.

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

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

With an output schema present, the description doesn't need to document return shapes. The only required input is fully specified in the schema, and the description supplies the workflow context and token guidance that aren't available anywhere else.

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?

There is only one parameter and the schema already documents it as an absolute file path, so schema coverage is 100%. The description doesn't add new parameter semantics beyond confirming that the call targets one Office file, so the baseline score 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?

Description names a specific action and resource: it gathers all project-level information about one Office file in a single call. It enumerates the returned categories (VBA modules, UserForms, queries, worksheets, protection status), which makes its scope concrete and distinguishes it from the more granular list_* and read_* siblings.

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?

'Call this once per file before working on it' gives explicit positioning as the first step in a workflow. It doesn't spell out when to prefer a sibling tool instead, but the 'everything in one call' phrasing makes the aggregate-vs-specific distinction clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with them. Beyond that, it discloses two genuinely useful behaviors: values may be stale ('a formula whose inputs changed outside Excel shows its old result') and a hard call limit ('At most 20,000 cells per call'). These add real context the annotations and schema 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?

Three sentences, all of which earn their place: core operation, the subtle values-versus-formulas behavior, and the cell cap. The most important information is front-loaded, and there is zero filler or repetition of schema 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 tool with full annotations, a 100%-covered schema, and an output schema describing return values, the description covers everything an agent needs to invoke it correctly: what it returns, the key behavioral nuance (staleness), and the practical size limit. No critical gap remains.

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 elevates this by adding meaning to the include parameter (explaining the semantic difference between values and formulas and when each is appropriate) and to cell_range (the 20,000-cell cap). It does not add detail for file_path, sheet, or timeout, but those are already well documented 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 a specific verb and resource — 'Reads a range of cells from a worksheet and returns a grid of values, formulas, or both' — which states exactly what the tool does. It is clearly distinguished from siblings like xlide_write_cells (opposite operation) and xlide_read_module/xlide_read_form/xlide_read_query (different resources), and the values-vs-formulas distinction adds precision beyond the title.

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 explicit selection guidance for the include parameter: 'Ask for formulas when you need to understand what a sheet computes, and values when you need what it currently shows.' This is clear, decision-relevant context. However, it does not name alternative tools or state when not to use this tool versus a sibling such as xlide_write_cells or xlide_list_sheets, so it stops short of full exclusion 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by explaining that properties left at their defaults are not stored and therefore not listed, which helps an agent avoid misinterpreting missing properties as an incomplete result. This goes beyond what the annotations alone 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 two compact sentences with no wasted words. It front-loads the core action and outcome, then adds a key caveat about default properties and practical use cases. Every sentence earns its place.

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

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

For a simple read-only tool with an output schema and safety annotations already present, this description is complete. It explains what is read, the relevant detail about default properties, and practical scenarios, while the output schema covers return-value structure. No critical information needed to call or interpret the tool is missing.

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

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

The input schema has 100% description coverage, so the parameters file_path, form_name, and include_properties are already well documented. The description does not add extra parameter-level guidance beyond the schema, so it meets the baseline of 3 without needing to compensate for coverage gaps.

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

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

The description uses a specific verb and resource: 'Reads one form's design,' and enumerates exactly what an agent can expect—controls, names, types, containers, and developer-set properties. It clearly distinguishes this from sibling tools like xlide_list_forms and xlide_edit_form by focusing on reading a single form's design rather than listing or modifying 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?

The description provides clear use cases: 'understand a form's layout' and 'see which control an event procedure belongs to.' However, it does not explicitly mention when not to use this tool or name alternative tools, such as using xlide_manage_form or xlide_edit_form when modification is needed, so it falls short of a 5.

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

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

The description adds meaningful behavior beyond the readOnly/idempotent annotations: the attribute header is stripped, a content_token is returned and later used to refuse writes if the module changed, and line slices are 1-based and inclusive. These are non-obvious behaviors an agent needs to invoke the tool correctly.

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

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

The description is compact and well organized: lead with the tool's role, then the return value, then the token semantics, then the slicing behavior. Every sentence carries relevant information and nothing is redundant.

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

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

For a read tool with five parameters and an output schema, the description covers the important operational details: what is returned, how the header is handled, how the content_token flows into a write, and how slicing works. The schema fills in the remaining parameter specifics, 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 coverage is 100%, so the baseline is 3. The description adds useful parameter semantics by explaining that start_line and end_line define an inclusive 1-based slice, and by clarifying the default header-stripping behavior. This goes beyond the schema's brief parameter descriptions.

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

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

The description opens with 'The canonical way to read VBA' and specifies that it returns a module's source as the VBA editor shows it. This clearly identifies the resource (module source), the action (read), and sets it apart from sibling read tools like read_form or read_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?

Calling this the 'canonical way to read VBA' gives a strong usage signal and implies it is the default choice for module reading. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context by specifying the exact fields returned and clarifying that the formula is the full 'let ... in' expression as shown in the Advanced Editor, which is beyond what annotations provide.

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

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

Two sentences with no redundant information. The core purpose is stated first, followed by the formula format clarification. Every word contributes to understanding the tool's function.

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 presence of an output schema, the description does not need to detail return structures. It covers the key aspects of what is read and how the formula is represented. The tool is simple, and the description is sufficient for an agent to 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 both file_path and query_name are already well-documented. The description does not add additional parameter-specific meaning, but the schema fully covers them, 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 clearly states a specific verb ('Reads'), a resource ('one query'), and the exact content returned (M formula, description, group, load target, refresh settings). It distinguishes itself from siblings like xlide_write_query (write) and xlide_list_queries (list all) by focusing on a single query's detailed read.

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 implies usage for reading a single query's details, but does not explicitly state when to choose this over alternatives like xlide_list_queries or xlide_write_query. No exclusion criteria or context is given, so an agent must infer the appropriate use case.

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 this as destructive and non-read-only, so the description does not need to restate that. It adds valuable behavioral detail beyond annotations: the file is saved as part of the operation, procedure calls are not rewritten, and host-owned document modules are protected from renaming. This level of disclosure is far more than the annotations provide 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?

The description is only three sentences, front-loaded with the core action and then covering caveats. Every clause adds useful information: what happens, what does not happen, what to do instead, and which modules are unsupported. There is no filler or repetition.

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

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

Given the annotations, 100 percent parameter coverage, and an output schema, the description provides a complete picture for correct invocation. It covers the destructive nature through annotations, the side effect of saving, the project-wide scope limitation, and the prerequisite search step. The optional parameters are adequately surfaced by the schema, so nothing essential is missing.

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

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

The schema already documents all five parameters, so the baseline is 3. The description adds meaningful parameter context beyond the schema by explaining that document modules cannot be renamed, which directly informs the module_name parameter. It does not explain the two optional booleans in depth, but the schema already names them and the description's added module_name constraint justifies a slight boost.

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 an exact operation: renaming a VBA module and saving the file. It also clarifies what the operation does not do, which distinguishes it from related module tools like xlide_write_module or xlide_delete_module. The explicit mention of xlide_search_modules and document-module limitations removes ambiguity.

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 a clear when-not case: document modules such as ThisWorkbook cannot be renamed. It also instructs the agent to search for the old name first with xlide_search_modules, which is a useful precondition. It could be even stronger by stating explicitly that this tool should be used only for renaming, not for rewriting module contents, but the guidance is already clear enough not to confuse 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds semantic context about rule entries (e.g., VBA compile failure mirroring), but does not disclose behavioral details such as output limits, ordering, or error conditions. This matches the calibration example where such gaps cap the score at 3.

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 fluff. The resource is identified up front, the content is summarized in one sentence, and the usage guidance is a compact second 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 simple read-only lookup tool with zero required parameters, full schema coverage, and an output schema, the description fully covers what the tool is and when to use it. 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%: both `code` and `search` have textual descriptions, including default behavior ('Empty lists them all'). The description adds no parameter-level meaning beyond what the schema already provides, so 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 opens with 'The analyzer's rule catalogue', identifying a specific resource, and enumerates the exact content of each entry (title, default severity, category, VBA compile mirror, MS-VBAL section). It also gives two concrete use cases, making it unmistakably distinct from analysis or compile-checking siblings.

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 final sentence states clear scenarios: 'explain a code to the user' and 'decide whether a finding is a compile error or a judgement call.' It does not explicitly name alternative tools or when-not-to-use conditions, but the usage context is unambiguous.

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

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

Beyond the annotations, the description reveals key behaviors: the document opens read-only by default, closes without saving unless save=true, returns the procedure's return value and logs, reports timeout by terminating the application, and lacks call-stack info for existing procedures. This is rich, accurate 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 compact despite covering environment constraints, defaults, return values, error behavior, an important limitation, and a safety instruction. Every sentence adds useful information, and the core action is stated first.

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, the description covers prerequisites, default behaviors, return values, timeout semantics, error limitations, and the safe alternative. The output schema handles return-value structure, so nothing needed for correct invocation 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 meaningful semantics for parameters such as read_only and save by explaining their interaction, and for timeout by describing what happens on expiry. This goes beyond the schema's field-level definitions.

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: it runs a procedure that already exists in an Office file. It also distinguishes itself from the sibling xlide_run_vba by noting that call-stack instrumentation applies to injected source, not to procedures already in the document.

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 names xlide_run_vba as the alternative when failing line and call stack are needed, giving a concrete selection condition. It also gives environment prerequisites (Windows, application installed) and instructs the agent to ask the user before running a data-changing 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?

Annotations are minimal (readOnly=false, idempotent=false, destructive=false), so the description carries the burden. It discloses key behavior: tests are run individually, hangs become timeouts without blocking others, and the result format includes assertion message, failing line, call stack, and logged output. It also mentions that the harness provides PyvbaAssert and PyvbaAssertEqual. It does not specify whether tests can have side effects, but given destructiveHint=false and the test-runner purpose, this is acceptable.

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 4 sentences with zero wasted words. It front-loads the core purpose, then adds prerequisites, behavioral guarantees, and test-authoring guidance. Every sentence serves a distinct informational need and the structure makes it easy to scan.

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

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

Given the moderate complexity (3 params, output schema present), the description covers what an agent needs: what tests are run, isolation and timeout behavior, what the result contains, platform prerequisites, and the required assertion library. Even though output schema exists, the description's explanation of return values is a useful supplement and not redundant. There are no glaring gaps that would prevent correct invocation.

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

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

Schema coverage is 100%, so the schema already documents each parameter (file_path absolute path, timeout seconds per test, module_name module filter). The description adds context about isolation and return format but does not add any extra meaning to the parameters themselves. Baseline 3 is appropriate because the schema does the heavy lifting.

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 a specific verb and resource: it opens and runs VBA tests in an Office file, with a precise inclusion criterion (zero-argument procedures whose name starts with Test). This clearly differentiates it from sibling tools like xlide_run_macro (runs a single macro) or xlide_run_vba (runs arbitrary VBA), making selection 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?

It states clear prerequisites (Windows only, with the application installed) and defines the test selection rule, which tells the agent when this tool is appropriate and what it expects. It does not explicitly name alternatives or say 'use run_macro instead', but the test-specific scope and prerequisites give sufficient context to choose it over siblings.

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, it discloses Windows-only behavior, no-dialog error reporting with failing line and call stack, PyVbaLog as the output channel, and that Debug.Print/MsgBox fail under automation. It also states that missing file_path creates a new empty document, and the destructiveHint annotation is consistent with executing arbitrary code.

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 action, then gives platform, use cases, default-document behavior, error shape, and output mechanism. Every sentence contributes a distinct fact; 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 7-parameter execution tool, the combination of schema descriptions, annotations, output schema, and this description covers what the tool does, how to get results, how errors surface, and platform constraints. Nothing essential is missing for an agent to 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 the schema already explains all 7 parameters. The description adds one param-related behavior, behavior when file_path is omitted, but that is already implied by the schema description, so no substantial extra semantic value is added.

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 the exact operation: inject VBA source into a document and call one procedure, with a platform constraint. It also distinguishes itself from persisted-module tools by framing it as a way to check code before writing it to a file and to read data no existing macro exposes.

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: for testing code before writing it to a file and for extracting values not exposed by existing macros. It doesn't mention when not to use it or name sibling alternatives like xlide_run_macro, but the context is clear enough to route an agent.

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 false, so the safety profile is covered. The description adds useful behavior beyond that: it discloses the return shape (module, line number, line content) and the default plain-text vs regex mode, which helps the agent anticipate 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?

Three sentences with no filler or repetition. The first sentence front-loads the core behavior and output; the second gives the usage scenario; the third covers the mode toggle. Every sentence earns its place.

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

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

The output schema covers return values, annotations cover side-effect safety, and the description covers when to use the tool and the key behavioral modes. The only potential concern, result limits, is documented in the schema via max_results. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful param context by specifying that is_regex uses a 'Python regular expression' and by framing query as a symbol lookup for refactoring, which goes slightly beyond the bare schema descriptions.

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

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

The description states a specific action ('searches every module's source'), the target resource ('an Office file'), and the concrete return content (module, line number, and line itself). This clearly distinguishes the tool from sibling module-read tools like xlide_read_module by emphasizing the across-modules search 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 gives an explicit use case: 'find where a name is declared or used before changing it.' It does not list exclusions or alternatives, but the context is clear enough for an agent to know when this search 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?

The description adds substantial behavioral context beyond the annotations: it saves the workbook as a side effect, an empty macro clears the link, the macro must already exist (otherwise failure), and it warns about the corruption risk if shape parts are inconsistent. This goes well beyond the destructiveHint and idempotentHint flags, giving the agent a realistic expectation of side effects and prerequisites.

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: the main action is front-loaded, and each subsequent sentence adds distinct value (clearing behavior, when to use, prerequisites, and a warning). There is no fluff or redundancy, making it efficient for an agent to parse.

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

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

The description covers purpose, usage timing, prerequisites, side effects, and limitations (only existing shapes). With an output schema and annotations, this is sufficient for an agent to invoke the tool correctly. It doesn't detail error handling or what happens if the shape isn't found, but that is likely covered by the output schema or expected behavior.

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

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

Schema coverage is 100%, and the schema already documents all four parameters, including the macro format (Proc or Module.Proc) and the empty-clears behavior. The description reinforces this and adds a note about writing the macro first, but this is more of a usage guideline than new parameter semantics. Thus a 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?

The description clearly states the tool changes which macro a shape runs when clicked and saves the workbook. It specifies the resource (existing shape/button) and the action (changing its OnAction), and explicitly notes it does not add or delete shapes, which helps distinguish it from shape management tools. While it doesn't name specific sibling tools, 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 gives concrete usage timing: use it after writing a Sub or after renaming a macro, because nothing rewrites an OnAction. It also explicitly states it only works on existing shapes and does not handle adding/deleting, which tells the agent when not to use it. It doesn't name alternative tools, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety. The description adds useful context beyond that: the nature of checks (structural vs code) and a recommendation for pre-risk usage. It does not disclose details like return format or failure behavior, but the output schema likely covers that, and annotations carry the safety burden.

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 first states purpose and examples, the second clarifies scope and routes to a sibling, the third gives usage timing. No fluff, front-loaded with the primary 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?

For a validation tool with an output schema present, the description is complete: it explains what it checks, what it is not for, and when to use it. The agent has enough to decide when to call it and what to expect, without needing additional details like return format (covered by output schema) or performance.

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% and the single parameter file_path is already described as 'Absolute path to the Office file.' The description adds no additional parameter semantics, which is acceptable given the schema already documents it fully. 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 clearly states the verb 'checks' and the resource 'VBA project', and specifies the scope as 'structural problems' with concrete examples (records disagreeing, missing module in container). It explicitly distinguishes from xlide_analyze for code analysis, so an agent can immediately tell this tool apart from its closest sibling 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?

The description gives explicit usage guidance: it is for structural validation ('about the container, not about the code') and explicitly says to use xlide_analyze for code. It also recommends calling it 'before risky work on an old or repaired file', giving a clear when-to-use condition.

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 destructive and non-read-only behavior, but the description adds substantial context: the file is saved, formulas are recognized by '=' prefix, overwriting a formula removes it, only touched rows are rewritten, and nothing recalculates until Excel opens. This goes well beyond the annotations and meaningfully discloses side effects.

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

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

The description is front-loaded with the core operation and then efficiently covers formula behavior, overwrite semantics, preservation of other workbook content, user consent, and recalculation timing. Every sentence contributes useful information without redundancy.

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

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

Given the write operation's complexity, the description covers the essential behavioral context: what is written, how formulas are distinguished, preservation of non-touched content, user-consent requirement, and recalc behavior. An output schema exists, so return-value documentation is not needed. The description is complete for safe and correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real parameter semantics beyond the schema: each row of data maps to a sheet row, formula strings must be written as in Excel 365 without _xlfn prefixes, and non-formula strings are values. This clarifies the data parameter in a way the schema alone 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?

The description states a specific verb and resource: 'Writes a rectangular block of values and formulas into a worksheet, starting at one cell, and saves the file.' It clearly distinguishes this from read/format/manage siblings by specifying it writes cell content. The scope is unambiguous and actionable.

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

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

The description gives clear context for when to use the tool: writing values/formulas into worksheet cell blocks. It also includes an explicit safety guideline: 'Ask the user before overwriting cells that hold data.' It does not explicitly name alternatives or exclusions, so it falls just short of a 5.

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

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

Annotations already flag destructive and non-read-only behavior, so the description doesn't need to restate those. It adds meaningful specifics: full-source replacement, attribute-header management, conditional refusal via expected_content_token, diff read back after saving, and explicit user-consent requirements 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?

The description is a dense but well-organized paragraph: core action first, then destructive semantics, creation behavior, concurrency token, return diff, follow-up analyze, and authorization caveats. No sentence is filler; the layout tracks the order an agent needs to reason through a write.

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 mutating tool with 8 parameters and an output schema, the description covers the behavioral corner cases: replacement semantics, class creation, stale-write refusal, diff display, post-write analysis, and protected/signed consent. It also explicitly delegates follow-up validation to xlide_analyze, leaving no obvious gap 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?

With 100% schema coverage the baseline is 3, but the description goes well beyond it: it clarifies that source must be the module body only, that kind='class' creates a class module, that expected_content_token enforces optimistic concurrency, and that include_diff can be disabled in loops. This maps precisely to the optional parameters and makes their usage concrete.

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

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

The description opens with 'The canonical way to change VBA' and then specifies exactly what the tool does: writes a module's source into the Office file, saves it, replaces the whole source, and creates modules if missing. It clearly distinguishes the operation from read/delete/rename siblings in spirit, though it never names an alternative tool explicitly.

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

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

It tells the agent to pass expected_content_token from a prior read, to call xlide_analyze after the write, and to ask the user first for protected or signed projects. However, it never contrasts itself with alternatives like xlide_import_modules or xlide_write_query, so the 'when not to use' guidance is only implied by the word 'canonical'.

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