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

Annotations only carry openWorldHint, so the description carries the burden of behavioral disclosure. It discloses that wrong-width rows are rejected before anything is written, that the response returns the CURRENT tableId after relocation, and that read-back triggers recompilation. It does not mention permission requirements or error behavior, but the provided side-effect details are valuable and non-obvious.

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

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

The description is four sentences and every sentence carries distinct information: scope, unsupported DTOs, width constraint, blank-cell encoding, alternative routing, and response side effects. It is dense but not bloated, and the core purpose 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?

For a nested-payload tool with no output schema, the description covers the critical behavioral contract: rejection atomicity, merged-region handling, tableId volatility, and recompilation. Combined with the fully described input schema, it gives an agent enough to invoke the tool correctly, though the exact full response shape is not specified.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic guidance beyond the schema: the all-columns width requirement, the '{ value: null }' blank-cell encoding, and the instruction to preserve covered placeholders for merged regions. These details help the agent construct correct appendData payloads.

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 'Append RawSource rows to an existing table', a specific verb plus resource, and immediately distinguishes itself from typed append DTOs and sibling actions like update_table and delete actions. The scope is precise and unambiguous.

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

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

It explicitly states when to use this tool (appending raw rows) and when not to: 'For modifying or reordering use a narrow raw action tool or update_table; remove rows/columns only with the corresponding delete action.' This directly routes the agent away from inappropriate sibling tools.

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

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

With only openWorldHint as annotation, the description carries the behavioral disclosure burden and does so thoroughly. It reveals the volatile location-derived tableId, explains that the response returns current tableId and previousTableId when relocated, and discloses the non-obvious recompile behavior triggered by reading the table back. This is exactly the kind of behavioral context an agent needs beyond the schema.

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

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

The description is dense but every sentence earns its place: main action first, then the data-structure contract, position semantics, the volatile-id warning, and the recompile side effect. Nothing is redundant, and the most decision-relevant information 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?

For a mutating table operation with no output schema, the description covers everything an agent needs: what to pass, how cells map to columns, where columns are added, how to handle the volatile tableId, and what follow-up calls may see after recompile. It is complete relative to the tool's complexity and the sibling set.

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 significant semantic value beyond the schema. It re-explains the 'cells' 2D structure in clearer terms, clarifies 0-based positioning, and explains the tableId volatility and response contract. While projectId and response_format gain little new meaning, the tricky parameters are well supplemented.

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 ('Add ONE OR MORE columns to the END of a table's raw source') and immediately distinguishes this tool from related siblings like openl_insert_table_columns and openl_append_table_rows by emphasizing END, columns, and raw source. It also clarifies the 2D 'cells' array orientation, leaving no ambiguity about what the 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 gives clear usage context: append at the end, works on any table type because it operates on raw source, and supports one or many columns at once. It does not explicitly name sibling alternatives or state when not to use them, but the placement and raw-source emphasis provide enough contextual guidance for an agent to select it correctly in most cases.

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 include openWorldHint=true, so the description carries most of the burden. It discloses important behaviors: it appends to raw source, can change the table's ID due to relocation, returns current tableId and previousTableId, and triggers a recompile via reading the table back. This exceeds the minimal safety disclosure expected.

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

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

The description is long but every sentence earns its place: it covers data structure, positioning, raw source, ID volatility, and recompile side-effect. It's front-loaded with the core append behavior. 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?

For a 4-param tool with no output schema and only openWorldHint annotation, the description is quite complete. It explains side effects that an agent must know (ID changes, recompile trigger). It doesn't detail response format beyond tableId/previousTableId, but since no output schema exists, a brief note on response shape could push it to 5.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds useful context about the 2D array orientation and blank-cell syntax, but it doesn't add much beyond the schema's own descriptions. 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 clearly states the tool adds one or more rows to the end of a table's raw source, with specific details on the 2D array structure. It distinguishes itself from siblings like openl_insert_table_rows (adds rows elsewhere) and openl_update_table_row by emphasizing 'END' and 'raw source'.

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

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

The description gives clear usage context—when to use it to add rows, how to handle blanks, and mentions it works for any table type because it operates on raw source. It doesn't explicitly contrast with openl_insert_table_rows or openl_append_table (which may be a high-level wrapper), but the positional and raw-source details provide enough guidance. No explicit exclusions, though.

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 destructiveHint=true, and the description adds valuable specifics: the stored conflict analysis is discarded, files and branches are untouched, and the workflow can be recreated by rerunning the merge. This gives the agent a precise mental model of the 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 tightly written sentences: the first states the action, and the second qualifies scope and recovery. There is no filler, and the most important behavioral distinction 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?

For a simple cancellation tool with no output schema and strong annotations, the description fully covers what happens, what does not happen, and how to undo the state change. No critical information 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%; both projectId and response_format have detailed descriptions, including how to obtain projectId and what each response_format value means. The tool description itself adds no parameter-level meaning, but the schema fully carries that 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 states a specific verb ('Abort') and resource ('pending merge-conflict workflow'/'session state'), and immediately clarifies that it does not modify files or branches. This makes it clearly distinct from sibling tools like openl_get_merge_conflicts and openl_merge_project_branches.

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 frames when to use this tool: when a pending merge-conflict workflow needs to be aborted, and it notes that rerunning the merge recreates the analysis. It does not explicitly name alternatives or exclusions, but the usage context is unambiguous enough for 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?

Even though annotations already declare readOnlyHint, idempotentHint, and openWorldHint, the description adds valuable behavior: 'without changing Git,' precise semantics of status='mergeable' vs 'up-to-date,' and what canMerge reflects after permission/protection/lock checks. 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?

Four tightly packed sentences, no filler; the most important discriminator ('not a conflict preview') appears early. Each sentence adds a distinct piece of information needed to use the tool correctly.

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 check tool with no output schema, the description covers the outcome semantics (status, canMerge), mode direction, permissions/blockers, and target discovery. An agent has enough to select and invoke it correctly without needing to infer 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%, so the baseline is 3, but the description adds meaningful parameter context: mode receive/send direction, otherBranch as source or target depending on mode, and the discovery path for valid otherBranch values. ProjectId and response_format are already well described 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?

Description opens with a specific verb and resource: 'Check merge direction, branch relationship, permissions, and blockers without changing Git.' It distinguishes itself from openl_merge_project_branches by explicitly stating it is not a conflict preview, so an agent can differentiate it from the sibling merge tool.

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 states when this tool is appropriate (pre-merge check, no mutation) and when it is not ('This is not a conflict preview'), pointing to openl_merge_project_branches for conflict discovery. It also directs the agent to openl_list_project_branches(scope='repository') to discover targets, including the caveat that a valid target may not hold the project yet.

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 destructiveHint=true, and the description adds concrete behavioral detail: unsaved changes trigger an error unless saved or discarded, and discarding requires explicit user confirmation. This meaningfully extends the annotation by explaining the destructive path and the safeguard. No contradiction with annotations was found.

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 compact sentences front-load the core action and immediately cover the conditional close paths and the confirmation requirement. Every sentence contributes decision-relevant information, with no filler or redundant restatement 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?

For a destructive closure tool, the description covers the main state-dependent branch, the user-confirmation loop, and the data-loss prevention rationale. With no output schema, return values are not described, but the fully documented input schema and workflow covers what an agent needs to call the tool correctly.

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

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

Input schema descriptions cover 100% of the parameters, so the baseline is 3. The description reinforces relationships between saveChanges/comment, discardChanges/confirmDiscard, and the EDITING status, but the schema already documents these details. It adds context, though not substantial new semantic information 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 opens with a specific verb and resource, 'Close a project,' which cleanly distinguishes it from save, open, and delete siblings. It further clarifies that closing may involve saving or discarding changes, making the action's finality clear. It does not explicitly name sibling tools for differentiation, so it misses a 5.

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

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

The description gives an explicit conditional workflow: if the project is EDITING, either pass saveChanges with a comment or discard; when discarding, ask the user first and call again with confirmDiscard: true. This is clear usage context and a safety protocol. It does not explicitly contrast with alternatives like openl_save_project, so it stops short of a 5.

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

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

With only openWorldHint=true in annotations, the description carries the behavioral burden — and it delivers: it discloses that the copy is staged in the working copy and requires openl_save_project to commit, that intermediate folders are auto-created, and that a conflict yields HTTP 409. This is exactly the side-effect and failure-mode context an agent needs beyond the bare 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?

Every sentence earns its place: core behavior, folder auto-creation, the no-overwrite failure mode, staging/commit requirement, branch pinning, and use cases. Dense but well front-loaded — the most decision-critical facts (no overwrite, 409, staged copy) appear in the first three sentences.

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 5-parameter tool with no output schema and a large sibling family, the description covers behavior, failure modes, side effects, and the follow-up workflow (commit with openl_save_project) — nearly everything required to invoke it correctly. The only gap is that the return value/response shape is never mentioned, which matters slightly more because no output schema exists.

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 five parameters, including path formats and branch behavior; the baseline 3 applies. The description adds minor reinforcement ('Use branch to pin the project's branch') but no new parameter-level meaning beyond what the schema already states.

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

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

The first sentence names a specific verb and resource — 'Copy a file within a project to a new project-relative path' — and the endpoint mapping POST /projects/{projectId}/file-copy confirms the operation. The closing use-case guidance ('scaffold a new module from an existing one or clone a test set') further distinguishes it from sibling file operations like move, write, or delete.

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

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

The description gives clear when-to-use context ('Use this to scaffold a new module from an existing one or clone a test set') and an explicit exclusion: 'There is NO overwrite option — if destinationPath already exists the call fails with HTTP 409; choose a different destination or delete the existing file first.' It stops short of naming sibling alternatives (e.g., openl_move_project_file or openl_write_project_file) by name, so it earns a 4 rather than a 5.

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

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

With annotations providing only openWorldHint and no read-only/destructive hints, the description carries the behavioral burden. It discloses that the copy is server-side, preserves structure, and 'remains in the working copy,' which is important context for persistence. It does not fully explain overwrite behavior or failure cases, but the core side-effect model is transparent.

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

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

Three sentences carry the essential purpose, usage, and persistence caveat. Information is front-loaded: the verb and resource appear immediately, optional behaviors are compactly listed, and the working-copy note is placed last where it is easy to remember. There is no redundant or filler content.

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

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

For an 8-parameter tool with no output schema and sparse annotations, the description covers the key operational context: what is copied, where it goes, how to create a new module, and how persistence works. It could be more explicit about cross-project limitations and the exact meaning of 'replace the source properties,' but the essential guidance is present.

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 by clarifying that moduleName/name are destination values, that modulePath creates a new .xlsx module, and that properties can be replaced. This goes beyond the schema's basic 'name' and 'pattern' descriptions, though it does not elaborate on projectId or response_format beyond what the schema already states.

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: 'Copy a table inside the same project using Studio's server-side copy operation.' It further distinguishes this from file copying by emphasizing preserved table structure such as formatting, merged cells, and comments, and by naming table-focused options like sheet names and module paths.

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 states what is needed to use the tool ('Provide the destination module and new table name') and outlines the optional variations: choosing a sheet, creating a new .xlsx module, or replacing properties. It also gives a key follow-up action ('use openl_save_project for Git-backed projects'). It does not explicitly name sibling alternatives or exclusion conditions, 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?

Beyond the annotations, it discloses atomic commit/indexing, server-side full-structure copying, descriptor renaming, default-vs-target branch behavior, return values, and failure modes (collision, missing source, missing permission). There is no contradiction with the annotations, and the side effects are clearly described.

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

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

The description is dense but well structured: objective first, then modes, branch default, return values, and errors. Every sentence carries useful decision-relevant information with 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 two-mode, six-parameter mutating tool with no output schema, it states what is returned, how the caller should obtain prerequisite IDs, how errors surface, and what is unsupported. An agent has enough to invoke it correctly and recover from likely failures.

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 all six parameters in detail (100% coverage), so the baseline is 3. The prose adds cross-parameter meaning by tying the template choice to the two modes and clarifying that branch/projectName semantics apply consistently to both creation and copy.

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 (create/copy) on a specific resource (OpenL project) and separates the two modes by the template argument. It clearly distinguishes this from branch-creation, save, and deploy siblings by focusing on project creation with commit.

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 invocation rules: omit template for blank creation, pass an exact opaque projectId from openl_list_projects for copying, omit branch for default, and pre-call openl_list_branches to avoid accidental branch creation. It names an exclusion (local repositories are not supported), though it does not explicitly contrast itself with close alternatives like openl_create_project_branch.

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

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

With only an openWorldHint annotation and no read-only or destructive hints, the description carries the behavioral disclosure burden. It goes beyond the title by explaining that the branch may originate from a specific revision, tag, or branch, and that HEAD is used by default. It does not describe failure modes, but the core mutation and default behavior are transparent.

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

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

Three short sentences lead with the core action, then explain the branching sources and default revision. Every sentence adds useful information with 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?

For a simple creation tool, the description plus full schema coverage gives the agent what it needs to invoke correctly: required parameters, default behavior, and response format options are covered. No output schema exists, and the description doesn't specify the return shape or error-on-existing-branch behavior, costing one point.

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 only restates the revision default already present in the schema and adds 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 uses a specific verb and resource ('Create a new branch in a project's repository') and clarifies the revision source, including tags and other branches. This scope clearly differentiates it from sibling branch tools like list/delete/merge branches.

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

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

The description provides clear context for when to use this tool: when a new branch is needed in a project repository. It doesn't explicitly name alternatives or state when not to use it, but the operation is unambiguous so the agent can infer the correct choice.

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 only annotation is openWorldHint, so the description carries the behavioral burden, and it does so well: it discloses unsupported DTOs, the style-rejection behavior, the need for covered cells/spans, and the fact that the response is metadata, not a compilation result. These are exactly the non-obvious behaviors an agent needs before calling.

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 then adds each constraint as a separate compact sentence: DTOs, module modes, source construction, style, and response semantics. There is no filler or redundant explanation.

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

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

For a complex nested-source tool with no output schema, it covers the payload shape, module creation mode, source construction, style limitation, and the follow-up status call. It stops short of describing what metadata fields the response contains, which would have made it fully self-contained.

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 83%, so the baseline is 3, and the description largely restates what the schema already documents, such as moduleName vs modulePath, style rejection, and required table fields. While 'Build the exact OpenL grid from the bundled guides or copy an existing raw source' adds some practical guidance, the 'Requires moduleName plus table...' phrasing omits projectId, so it earns no higher credit.

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

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

The opening sentence names a specific action and resource: create a table from its complete RawSource 2D cell matrix. This clearly separates the tool from project creation and table mutation tools via the create + RawSource 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?

It gives concrete conditions: use moduleName for an existing module, pass a .xlsx modulePath to create a new module, and call openl_project_status afterward. It also explains that typed table creation DTOs are unsupported, though it does not explicitly name update/copy sibling tools as 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?

Even though annotations already declare destructiveHint and openWorldHint, the description adds significant behavioral detail: deletion is permanent, a deletion commit may be created, confirmProjectName must match the current backend name, and the handler reads the project immediately before deleting. This gives the agent a clear and actionable safety model 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 tight sentences front-load the action, then cover side effects and the safety requirement. Every sentence contributes distinct information: what the tool does, what side effects may occur, and what safeguards and parameters matter.

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

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

For a destructive tool with complete schema coverage and meaningful annotations, the description is sufficient. It covers permanence, repository side effects, safety confirmation requirements, and commit behavior, while the response_format enum in the schema defines the expected output shapes.

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 still adds value by explaining that confirmProjectName must match the project's current backend name and that the handler reads the project right before deletion. It also clarifies that the optional comment becomes the deletion commit message, reinforcing and extending the schema's 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 states a specific verb and resource: 'Permanently delete a project through Studio,' and further clarifies that deletion may create a commit in the design repository. This unambiguously distinguishes it from sibling tools like openl_delete_project_file, openl_delete_project_branch, and openl_delete_table.

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

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

The intended context is clear: use this tool when you need to permanently remove an entire project, and the safety guard tells callers they must provide the exact current backend project name. It does not explicitly name alternatives or exclusion cases, but the operation and prerequisites are specific enough that an agent can correctly route to 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 flag destructiveHint and openWorldHint, and the description goes well beyond them by disclosing the internal preflight, the exact confirmation gates, the side effect of closing the project if open, and support for slash-containing branch names. No hidden destructive behavior is omitted.

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

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

The description is dense but each sentence covers a distinct, necessary fact for safely invoking a destructive operation. The purpose is front-loaded, and the safety conditions are ordered logically from metadata check to preflight to confirmations and side effects.

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

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

For a destructive seven-parameter tool with no output schema, the description thoroughly covers preconditions, guards, confirmations, and side effects. The only minor gap is that it does not describe what payload or status the tool returns after deletion, which would be useful since no output schema exists.

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 relational meaning: force and confirmForce must appear together for protected branches, confirmBranchName must equal branch exactly, and confirmDataLoss acknowledges a reported risk. These relationships are not all explicit in the 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 opening sentence names a clear verb and resource ('Delete a branch from the repository hosting a project') and the rest of the description disambiguates this from create/list branch operations by detailing deletion-specific protections. It is unambiguous and distinct from sibling branch 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 context for when deletion is permitted: base branches are always rejected, protected branches require force plus confirmForce, and unsafe data-loss cases require confirmDataLoss. It does not explicitly name alternative tools, but there is no dedicated alternative deletion sibling, and the conditions effectively state when-not.

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

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

Beyond the destructiveHint annotation, the description discloses that deletion is staged in the working copy, requires a follow-up commit via openl_save_project, and that dangling references are auto-cleaned. These behavioral details are valuable and not present in the annotations.

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

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

Four sentences, each earning its place: purpose, REST mapping, staging/commit behavior, branch guidance, and destructive warning. Information is front-loaded with the core action 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?

Covers the essential deletion semantics, staging, branch handling, and destructive nature. No output schema exists, but the main return-format options are fully specified in the parameter schema. Minor omission: no explicit note about what happens to open file handles or if deletion fails on non-empty folders, but the description is otherwise sufficient for safe 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% and each parameter is already well-documented (e.g., path relative to project root, branch constraints, response_format enum). The tool description adds little beyond the schema, which is acceptable per the baseline.

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

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

States a precise verb + resource ('Delete a file or folder from a project by its project-relative path') and maps to a specific REST endpoint. This clearly distinguishes the tool from siblings like openl_write_project_file, openl_move_project_file, and openl_copy_project_file.

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

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

Gives explicit context: use for removing legacy assets or deprecating docs, pin branch via 'branch', and commit staged deletion with openl_save_project. Does not name alternative tools explicitly, but the workflow context is clear enough for an agent to select 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 only mark destructiveHint and openWorldHint, so the description carries the burden of explaining consequences. It goes well beyond that: the entire table is cleared regardless of type, the table no longer exists after recompile, stale ids are auto-resolved, and no auto-compile occurs afterward—so the agent knows to check project status. This richly complements the annotations and does not contradict them.

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

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

Four sentences, each earning its place. The primary action and scope are front-loaded, the alternative tool routing comes second, and the two behavioral caveats (stale-id resolution and no auto-compile) are compact and specific. No filler or repetition of the schema.

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

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

For a destructive table-level operation with no output schema, the description explains the effect, the alternatives, the stale-id behavior, and the recommended follow-up project-status check. The only minor gap is that it does not describe what the tool's response itself will look like or explicitly warn about irreversibility—though destructiveHint covers the latter implicitly. Overall, very complete for an agent to invoke correctly.

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

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

Input schema coverage is 100%, and the schema already provides detailed parameter descriptions, especially for tableId and projectId. The description adds one meaningful behavioral detail beyond the schema: stale ids are resolved automatically. This is helpful context for tableId semantics, though not strictly required given the schema's richness.

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

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

The description opens with a specific verb and resource: 'Delete an ENTIRE table from a project.' It clearly defines the scope ('whole table area is cleared... regardless of table type') and distinguishes itself from openl_delete_table_rows / openl_delete_table_columns, making the tool's unique purpose unmistakable.

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

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

The description explicitly tells the agent when to use this tool versus the row/column deletion siblings, naming the alternatives and the condition ('To remove only a row or column WITHIN a table'). It also provides post-action guidance: run openl_project_status afterward to confirm compilation and check for dangling references. This is actionable routing guidance.

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

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

The description goes well beyond the destructiveHint annotation by explaining the actual destructive behavior (shifting columns, leading-label protection), the possibility of id changes, the response always returning the current tableId, and the recompile side effect. This is rich behavioral disclosure.

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 carries necessary information, and the core operation is front-loaded in the first clause. The description is long, but the complexity of the tool (id volatility, raw-source semantics, recompile behavior) justifies the length. Some sentences are dense and could be split, but nothing is filler.

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

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

For a destructive mutation tool with no output schema, the description covers the essential context: what gets deleted, what cannot be deleted, how positions work, how ids may change, what the response contains, and a caveat about compilation. An agent has enough to call this tool correctly and handle side effects.

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 semantic context beyond the schema: 0-based indexing clarifies the header row, column 0 as leading labels, and the default count of 1. It reinforces and slightly extends the schema explanations 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 clearly states the verb 'delete' and resource 'columns from a table's raw source', specifying position-based deletion and the shifting behavior. It also clarifies the leading-label column cannot be deleted, unambiguously distinguishing it from other table mutation 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 context is clearly defined: it operates on the RAW source, works for any table type, and explains the exact positional semantics. It doesn't explicitly name sibling alternatives or say when not to use this tool, but the 'raw source' framing and row/column behavior give sufficient guidance for correct selection.

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

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

Annotations already indicate destructive and open-world behavior, but the description goes much further: it explains row shifting, the protected header, table relocation causing tableId changes, the response returning the current tableId and previousTableId, and the recompile side effect. These are critical behavioral details beyond what the annotations or schema 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 relatively long but dense with necessary caveats: id volatility, recompile behavior, and response semantics. It is front-loaded with the core delete behavior and each sentence adds operational value, though a few details repeat what is already in the schema.

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

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

Given that there is no output schema, the description appropriately explains the key response detail, the current tableId and previousTableId, and it warns about the table's id changing. It covers destructive behavior, positional constraints, and the recompile side effect well, though it does not describe error cases or the full response shape.

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 even without extra parameter detail. The description reinforces the default count and the meaning of position, but most parameter semantics are already fully documented in the input schema; the main added value is clarifying that the returned tableId may change after relocation.

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 operation: deleting one or more rows from a table's raw source, starting at a given position, with rows below shifting up. It also clarifies scope limits such as the header row being undeletable and positions being 0-based, making it easy to distinguish from sibling tools like openl_delete_table_columns or openl_update_table_row.

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 useful context by noting that this operates on the RAW source and works for any table type, which implies broad applicability. However, it does not explicitly mention sibling alternatives or state when not to use this tool, such as when deleting columns or the whole table instead.

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 openWorldHint annotation is present, and the description adds meaningful context beyond it by disclosing the real-world consequence: rules are published to a deployment repository for runtime execution, meaning the deployment affects production behavior. This is exactly the kind of side-effect disclosure that helps an agent. It stops short of 5 because it doesn't address whether an existing deployment is overwritten or whether this action is reversible.

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, each earning its place: the core action, the behavioral consequence, and the critical name-vs-ID gotcha with a concrete example. No filler, no repetition of schema-level defaults.

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 production-deployment tool with openWorldHint and no output schema, the description covers the core semantics well but leaves gaps: no mention of what the response contains, no guidance on when to choose openl_redeploy_project over this tool, and no indication of whether deploying over an existing deployment is allowed. The params are well-documented in the schema, which carries some weight here, but the deploy-vs-redeploy decision is an important missing piece.

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 of 3 applies — every parameter already carries a rich description, including the exact source of projectId and the name-vs-ID rule for productionRepositoryId. The description's repository-name warning repeats what the schema already documents, adding no net new meaning for 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 states a specific verb ('Deploy'), resource ('a project'), and target ('production environment'), and adds what the operation actually accomplishes ('Publishes rules to a deployment repository for runtime execution'). It is clearly distinguishable from most siblings, but it does not explicitly differentiate itself from the closely related openl_redeploy_project, so it misses the top score.

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 core usage context is implied clearly: use this when deploying a project to production and publishing its rules for runtime execution. However, no alternatives or exclusions are named — notably there is no 'use openl_redeploy_project for existing deployments' guidance, which an agent would need given that sibling exists. The practical 'use repository name, not ID' advice is helpful but is a parameter-format rule, not a tool-selection rule.

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 declare readOnly, idempotent, and openWorld hints, so the safety profile is covered. The description adds substantial behavioral detail beyond those hints: the lazy one-level expansion model, `childrenTotal` instead of nested children, paging via `hasMore`/`nextOffset`, `notRetained` dropped sub-calls, the profiling prerequisite, and validity after the run completes. No statement contradicts the annotations.

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

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

The description is long but every sentence earns its place: it covers purpose, prerequisites, pagination, special cases like `notRetained`, and the alternative tool. It is front-loaded with the core action, then unfolds the lazy-tree model and paging details in a logical order. Given the tool's complexity and the absence of an output schema, the density is appropriate rather than 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?

With no output schema present, the description carries the full burden of explaining the return shape, and it does: the reply is a TreeChildrenView { children, total }, with `hasMore` and `nextOffset` for paging, and possible `notRetained` counts. It also covers lifecycle constraints (profiling run required, valid while the debug session is alive) and how to start from the /stack `tree` root. 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?

Even though schema coverage is 100%, the description adds meaning the schema alone does not fully convey. It explains that `step` must reference a node with `childrenTotal > 0`, that `offset`/`limit` page a loop's many sub-calls with `nextOffset`, and that `instance` picks the exact loop iteration. This transforms the parameters from raw JSON fields into a coherent iteration contract.

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: 'Load one level of a profiling run's executed call tree on demand.' It also distinguishes itself from sibling tools by naming the lazy-tree mechanism, the /stack `tree` root, and the alternative 'constant-size `profile` overview' for finding slow spots. This makes it unmistakable which operation this tool performs and how it differs from nearby tracing 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 explicitly states when to use this tool: only for a profiling run with `includeTree: true`, and only for expanding nodes whose `childrenTotal` is greater than 0. It also gives a clear when-not-to-use directive: 'To find what's slow use the constant-size `profile` overview instead; use this to walk one branch's call structure.' This is explicit routing with no ambiguity.

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 idempotentHint=true. Description adds key behaviors: never calls OpenL Studio (local), returns verbatim without truncation, fails with error naming unknown ids. No contradictions.

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?

Description is three concise sentences, each adding essential information. Front-loaded with the main action, no redundant words.

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

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

Despite no output schema, the description fully compensates by stating return format (full markdown), truncation behavior (none), error handling (fails for unknown ids), and prerequisite (use list_guides). Complete for a retrieval tool.

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

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

Schema coverage is 100% and the schema description already explains the parameter semantics. The description reinforces the size_bytes note and adds context about error behavior for invalid ids, providing additional value beyond 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 tool returns full markdown bodies of bundled documents by exact ids, distinguishing it from sibling openl_list_guides which lists guide metadata. It specifies the action (return bodies), the resource (guides by id), and scope (full, verbatim).

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

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

Explicitly instructs to look up ids with openl_list_guides first, warns about unknown ids failing, advises to mind size_bytes and fetch only what is needed. This provides clear when-to-use and prerequisites.

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 with rich annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds significant behavioral context: the conflicts are session-bound, the tool only works after a specific merge status, the same MCP server instance must be reused, and resolution is intentionally not exposed. These details go well beyond the structured annotations and inform safe 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 dense sentences with no filler. The first sentence front-loads the tool's purpose and output contents, the second establishes read-only intent and limits, and the third provides the required precondition and session-consistency warning. 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 low complexity (two parameters, no output schema), the description is complete: it summarizes the return contents, states the precondition, discloses the session-bound behavior, and explains the tool's role in the manual resolution workflow. An agent has enough context to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage, so the schema already fully documents projectId and response_format with helpful guidance. The tool description adds no additional parameter-level meaning beyond referring to the overall session context, 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 opens with a specific verb and resource: 'Get the pending merge conflicts stored in this Studio HTTP session,' and enumerates the exact contents returned (grouped file paths, BASE/OURS/THEIRS revision details, default merge commit message). It also distinguishes this from conflict resolution tools by stating the MCP server intentionally does not expose conflict resolution, making the tool's scope unmistakable.

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

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

The description gives an explicit precondition—'Available only after openl_merge_project_branches returns status='conflicts''—and provides an important session-scoped instruction to use the same MCP server instance. It also clarifies the tool is read-only evidence for manual resolution, which implies when not to use it, but it does not name alternative sibling tools such as openl_cancel_merge_conflicts or openl_read_merge_conflict_file.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description's main job is to add context beyond safety. It does add return-content context ('full project structure, configuration, and status') but does not explain how the 'include' expansions modify the response or what 'deleted' or 'descriptor' mean. No contradiction with annotations exists.

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

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

The description is compact and front-loaded with the core action and scope. There is minor redundancy between 'comprehensive project information' and 'full project structure,' and 'status' appears only in the second sentence, but overall the text is efficient and not padded.

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?

Basic invocation is clear: projectId is required and response_format is documented. However, with no output schema, the description does not adequately explain how the include options affect the returned data, nor does it clarify the difference between json and markdown outputs beyond what the schema already says. Given the large sibling set, some routing ambiguity 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%, and the schema already provides strong descriptions for projectId and response_format, plus the enum for include. The description adds only generic references to modules and dependencies, which are not clearly mapped to specific parameters or include values. The baseline of 3 applies because the schema carries the parameter documentation 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 uses a specific verb and resource ('Get comprehensive project information') and identifies the broad scope: details, modules, dependencies, metadata, structure, configuration, and status. It does not explicitly distinguish itself from related siblings such as openl_project_status or openl_list_project_modules, so it is clear but not fully differentiated.

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

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

The description gives no guidance on when to use this tool instead of alternatives. It does not mention that openl_list_projects supplies the projectId, nor does it note that openl_project_status or openl_list_project_modules might be more targeted for narrower needs. An agent is left to infer usage from the generic 'get comprehensive project information' phrasing.

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 (readOnly, openWorld, idempotent), the description details the upward traversal, concatenation order, skipping of missing levels, and listing of reference guide ids. No contradictions.

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 adds necessary information; front-loaded with primary use. No wasted words despite length.

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

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

Without an output schema, the description fully explains the return value (concatenated markdown or 'no files' note) and mentions related guide retrieval. Complete for a read-only retrieval tool.

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

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

Schema coverage is 100%, and the description adds value by explaining the 'folder' parameter's use for deeper file context and reminding to use exact 'projectId' from list. Slightly above baseline.

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

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

The description clearly states the purpose: resolving agent guidance (AGENTS.md hierarchy) for a project. It distinguishes itself from the sibling 'openl_search_project_files' by noting that for file-level search, use that instead.

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

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

Explicitly states 'call this BEFORE working on or creating anything in the project', providing clear context for when to use. Also mentions alternative for subtree search, aiding decision.

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 provide readOnlyHint, idempotentHint, and openWorldHint. The description adds value by stating 'Takes no arguments and never calls OpenL Studio,' which goes beyond the annotations and provides further behavioral transparency.

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, consisting of three sentences with no wasted words. It is front-loaded with key information: 'Read-only. Call this FIRST,' and each sentence contributes meaningfully.

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 has no parameters and no output schema, the description covers the essential context: what it returns, order of use, and that it never calls OpenL Studio. It is sufficiently complete for a simple initialization 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?

There are zero parameters and schema coverage is 100%. With no parameters, the description doesn't need to add parameter information, and the baseline of 4 is appropriate.

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

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

The description clearly states the tool's purpose: it returns the mandatory workflow protocol and workspace orientation. It explicitly says to call this first before any other openl_ tool, distinguishing it from 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 description provides explicit usage guidelines: 'Call this FIRST, once per session, before any other openl_ tool.' It also explains when to call openl_get_project_agent_context and mentions related documentation tools, offering clear context without 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?

Even with readOnly/idempotent/openWorld annotations, the description adds substantial behavioral detail: RawSource is authoritative, typed/parsed views are intentionally unsupported for round-trip safety, windowed responses carry totalRows, and stale table IDs are auto-resolved. It also explains why a window cannot erase omitted rows, which is valuable safety context.

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

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

The description is long but front-loaded with the core purpose and every sentence earns its place: caveats about typed views, slicing, window safety, alternative tools, and ID volatility. It is dense rather than bloated, though a slightly more compact treatment of the window-safety warning would improve it.

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

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

For a 6-parameter read tool with no output schema, the description covers return mode, row-slicing behavior, style enrichment, window limitations, and ID handling. It could say a bit more about the shape of the returned RawSource cell matrix, but the guidance is sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining how startRow/maxRows combine to slice a table, what styles=true produces, and why tableId is volatile. The projectId and response_format parameters remain covered by the schema alone.

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

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

The opening sentence states a specific action and resource: 'Get a table as its authoritative RawSource 2D cell matrix.' It also distinguishes itself from typed/parsed views and from the narrow raw table tools, so an agent can tell what mode this getter operates in.

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

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

The description gives clear usage context: use slicing with startRow/maxRows for large tables, and choose the narrow raw table action tools when a complete response would become a preview. It is slightly vague because 'narrow raw table action tools' is not explicitly enumerated, but the routing intent is 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, openWorldHint, and idempotentHint, and the description adds substantial behavioral detail: what executable, datatype, and vocabulary nodes contain; how dispatchers, self-loops, cycles, and inheritance are represented; how truncation and previews appear; and how JSON vs Markdown variants render. There is no contradiction 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?

The description is long but densely informative, moving from core behavior to mode selection to output rendering. Every sentence adds distinct value, including the Mermaid rendering details that matter for choosing response_format. There is no tautology 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?

For a tool with no output schema, the description covers the response semantics surprisingly well: it defines the adjacency-list graph, the node types, the meaning of dispatchers, self-loops, and cycles, and the differences between JSON and the Markdown variants. Required projectId and parameter constraints are already covered 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?

Schema coverage is 100%, so the baseline is a 3. The description adds conditional meaning beyond the schema, such as 'omit tableId for the whole project graph' vs 'provide tableId for its dependency/dependent neighborhood,' and explains how response_format affects the output. It does not independently document every parameter, but it meaningfully supplements 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: 'Get the table dependency graph as an adjacency list.' It then clearly distinguishes the two main call modes: whole project/module graph when tableId is omitted, and dependency/dependent neighborhood when tableId is provided. This makes the tool's purpose immediately distinguishable from sibling table tools like openl_get_table or openl_list_tables.

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 explains when to omit or provide tableId, when to use direction and depth, and how module and layer restrict the graph. It even points to openl_list_project_modules() for discovering module names. It stops short of explicitly naming sibling tools to avoid or saying 'use this instead of X,' so it is just below a 5.

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

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

With only openWorldHint=true in annotations, the description carries the disclosure burden and delivers: it flags the non-obvious gotcha that 'Pagination applies to test tables (not individual test cases)' with concrete examples, explains aggregation by table, and reveals the sequencing dependency on openl_start_project_tests. This is exactly the kind of behavioral context that prevents a wrong call, and it contradicts nothing in the annotations.

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

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

Four sentences with the high-value information front-loaded: purpose first, then the pagination gotcha, then the sequencing prerequisite. The example ('TestTable1' with 7 tests) earns its place, though 'Supports filtering failures and pagination (page/offset/size)' is mildly redundant with the schema.

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

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

For a 9-parameter tool with no output schema, the description compensates well by specifying the return structure, the pagination unit, and the required predecessor call. It leaves some edge behavior unaddressed (error behavior when no tests have run, unpaged behavior with huge result sets) and doesn't position itself against the two sibling test-result tools, but nothing critical is missing for making a correct call.

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 genuine value on top by explaining that page/offset/size operate on tables rather than individual test cases and that failures/failuresOnly filter at the aggregated level. The 'IMPORTANT' note reframes the pagination params in a way the individual param descriptions do not.

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

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

States a specific verb+resource ('Get full test execution results') and describes the return shape ('testCases array grouped by table'), which an agent can act on. It distinguishes from siblings like openl_get_test_results_summary largely through the word 'full' and the table-grouping detail, but it never names those siblings explicitly, so the differentiation is implicit rather than stated.

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 for when to call it: it is the full-results tool with table-level pagination, and it states the hard prerequisite 'Use openl_start_project_tests() first to start test execution.' It does not give when-not-to-use guidance or name alternatives such as openl_get_test_results_summary / openl_get_test_results_by_table, which is a mild gap given the sibling cluster.

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 only annotation is openWorldHint=true, which is weak — it does not declare read-only or destructive behavior, so the description carries most of the transparency burden. The description adds useful behavioral context (filtering to a single table's test cases, pagination support, and the prerequisite that test execution must already be started), but it leaves the safety profile implicit — read-only must be inferred from the verb 'get' — and says nothing about result volatility between calls or failure behavior. No contradiction with the 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?

Four sentences, all informative and front-loaded: purpose first, return scope second, pagination third, and the prerequisite last. The only minor waste is the overlap between sentence 1 ('filtered by specific table ID') and sentence 2 ('only test cases for the specified table'), and the pagination sentence partly duplicates schema content, but there is no fluff 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 10 parameters, no output schema, and only a weak openWorldHint annotation, the description covers the core workflow (filter by table, paginate, run tests first) and the rich schema covers parameter semantics. However, the agent is left without a picture of the return structure — 'test execution summary' is never concretely defined — and there is no guidance on polling/waiting for test completion or how this tool relates to the sibling summary tool. Adequate but with clear 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?

Schema description coverage is 100%: every parameter, including pagination mutual-exclusivity rules, defaults, limits, and the response_format enum, is documented in the schema itself. The description only echoes table filtering and pagination at a high level and adds no syntax or constraint information beyond the schema, 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 opens with a specific verb-resource pair: 'Get test execution results filtered by specific table ID,' and elaborates that it returns 'only test cases for the specified table,' which meaningfully scopes the operation. It is clear about what the tool does, but it never names sibling tools like openl_get_test_results or openl_get_test_results_summary, and its use of the word 'summary' creates a slight overlap with openl_get_test_results_summary, so differentiation relies mostly on the name and the table-ID qualifier.

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 one explicit sequencing rule — 'Use openl_start_project_tests() first to start test execution' — which is genuinely useful for an agent planning a multi-step workflow. However, it provides no guidance on when to choose this tool over the near-siblings openl_get_test_results and openl_get_test_results_summary, and no conditions for when not to use it, so the selection among the three results tools is left to inference.

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

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

The description discloses the key behavioral trait: it returns only aggregated statistics and deliberately omits the testCases array. It also surfaces the dependency on a prior test-start call. With only openWorldHint in annotations, this adds meaningful context beyond the structured data.

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 with no filler. It front-loads the purpose and return content, then gives the essential prerequisite. It avoids repeating 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?

With no output schema, the description covers the core return fields but leaves behavior for response_format variants, pagination, and failuresOnly implicit. It also does not state what happens if test execution has not been started, beyond the prerequisite instruction.

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 parameters including projectId, failures, failuresOnly, unpaged, and response_format. The description adds no parameter-level meaning beyond the schema, so it meets the baseline but does not go further.

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 and resource: getting a brief summary of test execution, and explicitly notes that detailed testCases are excluded. It differentiates itself from the detailed test-results siblings by what it omits, though it does not name the specific sibling tool to use for detailed results.

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 a clear, important prerequisite by instructing the agent to call openl_start_project_tests() first. However, it does not explicitly state when to choose this tool over openl_get_test_results or openl_get_test_results_by_table, leaving that differentiation implied rather than stated.

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, openWorld, and idempotent behavior, so the description does not need to restate those. It adds valuable behavioral context beyond annotations: the operation is only valid while the debug session lives, and the default response contains only name/description/value while withSchema adds a potentially large JSON Schema. This gives the agent clear expectations about side effects and response scope.

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 core purpose is front-loaded, the session-validity caveat is immediately relevant, and the withSchema warning earns its place without padding. No redundant restatement of already-schema-covered parameter details.

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

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

For a read-only, idempotent fetch tool with no output schema, the description adequately explains what is returned by default, what the optional schema adds, and the liveness constraint tied to the debug session. It could go further by mentioning that a stale parameterId might fail or become invalid after the session ends, but overall it gives enough context for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds meaning on top of that by explaining where parameterId comes from (a lazy ParameterValue from openl_inspect_trace_frame) and clarifying why withSchema should be used sparingly. This bridges the schema to the tool's workflow context, which is genuinely useful.

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 ('Fetch'), a specific resource ('full value of a parameter returned lazily'), and the exact condition that triggers its use (lazy: true with a parameterId). The title 'Expand Lazy Value' is reinforced and the tool is clearly distinguished from openl_inspect_trace_frame, which produces the lazy reference.

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 context is explicit: use this tool when openl_inspect_trace_frame returned a parameter with lazy: true, and only while the debug session remains alive. It also gives guidance on when to avoid withSchema due to its size. Slightly less than a 5 because it does not explicitly name alternative tools or say when not to use the tool, but the guidance is strong enough for correct selection.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description builds on them with substantial added context: it discloses that no connection is required, explicitly states it returns no configuration, credentials, or URLs (security-relevant), explains the build.id format and '.dirty' suffix, and interprets the 'unavailable' build.source edge case. This goes well beyond the annotation baseline.

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 and roughly 115 words — near the upper limit, but every sentence earns its place: field enumeration, a practical reporting tip (quote build.id), a security-relevant exclusion, and an edge-case interpretation. The purpose is front-loaded in the first clause.

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 required parameters and no output schema, the description must carry the return-value documentation, and it does: it enumerates all fields, explains the build.id disambiguation convention for nightly builds, covers the missing-metadata case, and confirms the tool's connectivity and data-safety profile. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% — the single response_format parameter has a full enum and per-value explanations. The description doesn't need to add parameter detail, and the baseline 3 applies because the schema fully carries that 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 opens with a specific verb and resource: 'Report this MCP server's own version and build identity for diagnostics and bug reports.' It enumerates the exact fields returned, and no sibling tool overlaps with version reporting, so an agent can distinguish it immediately from the 80+ operational tools in the sibling list.

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 ('for diagnostics and bug reports') and gives a condition that makes it uniquely available ('Needs no OpenL Studio connection'). It does not name alternatives or exclusions, but none are needed since no sibling performs version reporting.

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

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

With only openWorldHint in annotations, the description carries the full burden and exceeds it: it discloses column shifting, table relocation altering the location-derived id, the response returning current tableId plus previousTableId, and the absence of auto-compile with the read-back recompile trigger. No contradiction with the openWorldHint 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?

Front-loaded with the core operation, and every sentence earns its place: position semantics, cell array shape, raw-source guarantee, id volatility, and the recompile quirk. It is dense rather than brief, but the length is justified given the surprising id-relocation and compile behaviors an agent must know.

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 5-parameter mutation tool with no output schema and only an openWorldHint annotation, the description is remarkably complete: it covers operation semantics, coordinate conventions, cell structure, the id-change failure mode, response fields, and post-edit recompile behavior — everything needed to invoke it correctly and chain subsequent 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 baseline is 3; the description adds genuine value beyond the schema by clarifying the coordinate system ('row 0 is the header row, column 0 carries the leading labels' — so position 1 is the first data column), the cells dimensionality ('columns × that column's cells'), and instructing agents to use the returned tableId for subsequent calls.

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

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

States a specific verb and resource — 'Insert ONE OR MORE columns at position in a table's raw source, shifting the columns at and to the right of it' — with the key scope qualifier 'Operates on the table's RAW source, so it works for any table type.' This clearly separates it from siblings like openl_append_table_columns (append) and openl_insert_table_rows (rows).

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

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

Provides clear usage context: it operates on the raw source and works for any table type, and the position range '1..width (width appends to the end)' implicitly covers the insert-vs-append decision. However, it never names an alternative sibling explicitly nor states when-not-to-use conditions.

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

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

The description goes well beyond the openWorldHint annotation. It discloses that location-derived tableId can change when the table is relocated, that the response returns the current tableId and previousTableId when changed, and that the tool reads the table back to trigger recompilation. This is exactly the kind of operational behavior an agent needs to know and is not visible from the schema or 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?

The description is dense but every sentence earns its place. It front-loads the core operation, then covers positional edge cases, the critical id-volatility behavior, and the recompilation side effect. There is no redundant fluff or repetition of schema details that were already explained.

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 and the absence of an output schema, the description is remarkably complete. It explains the insertion position semantics, the raw-source behavior, the volatile tableId and how to obtain the current one, the previousTableId field, and the recompilation trigger. An agent has enough context to call it correctly and interpret the critical parts of the response.

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 parameters are already documented. The description adds valuable semantics beyond the schema: it explains that 'cells' is a 2D array with rows and per-row cells, clarifies 0-based positioning with row 0 as header and column 0 as leading labels, and warns that tableId is volatile. It does not add much about response_format, but the schema already documents that fully.

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: 'Insert ONE OR MORE rows at position in a table's raw source'. It clearly distinguishes this row-insertion tool from sibling operations like openl_insert_table_columns and openl_append_table_rows by emphasizing position-based insertion, RAW source, and row-shifting behavior.

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

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

The description provides clear context: it works on the RAW source, works for any table type, and positions range from 1..height where height appends to the end. It does not explicitly name alternatives or state when-not-to-use scenarios, but the positional and raw-source details give an agent enough context 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses substantial behavior: the response is trimmed by default and full: true lifts the trim; lazy values may need expansion; excludeStepValues resolves lazy values before comparison so neutral lazy factors are dropped; withHighlights returns an A1-keyed overlay plus raw grid; and a terminal session answers 409. There is no contradiction with the annotations — 'read' aligns with readOnlyHint=true, and openWorldHint aligns with the caveat that the world may have moved on.

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 single dense paragraph is information-rich with no filler — every clause covers a distinct behavior (frame contents, laziness, trimming, filters, highlights, 409 semantics). The core purpose is front-loaded and the terminal-session caveat is placed at the end. At roughly 180 words for a tool with 7 params and decision-table complexity it is appropriately sized, though the wall-of-text structure with nested parentheticals could be more scannable.

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 no output schema, the description carries the burden of explaining return values — and it does, enumerating input parameters, runtime context, result, sub-steps, decision, ruleNames, and the optional highlight overlay. It covers preconditions (suspended only), error semantics (409), parameter behaviors, and the openl_get_trace_value handoff for lazy values. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description genuinely adds meaning beyond the schema: it explains the 'why' of the filters (surfacing an anomaly), the interplay between onlyExecutedSteps and excludeStepValues, and the lazy-value resolution behavior before neutral comparison. It also frames the decision/ruleNames output as the 'killer feature' for per-rule breakpoints, giving purpose beyond the schema's bare property 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 names a specific verb and resource — 'Freeze and read the full state of one suspended stack frame' — and enumerates exactly what that state contains (input parameters, runtime context, result, sub-steps with computed values, decision/ruleNames). It clearly distinguishes itself from siblings like openl_get_trace_value (lazy expansion) and other trace tools. An agent can tell exactly what this tool returns without opening the schema.

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

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

The description gives an explicit precondition and exclusion: 'Valid only while suspended (a terminal session answers 409 — read its final state from the last returned stack)' tells the agent when not to call and what to do instead. It also routes lazy-value expansion to openl_get_trace_value and explains when the step filters are warranted (surfacing an anomaly among neutral factors). It stops short of contrasting with every related trace sibling (e.g., openl_expand_trace_tree, openl_watch_trace_cells), so the guidance is strong but not exhaustive.

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

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

Annotations already establish readOnly, idempotent, and open-world behavior, so the bar for additional disclosure is lower. The description adds useful behavioral detail: both repository id and name are accepted, matching is case-insensitive, and agents should not invent example values. This goes beyond the annotations and helps correct 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?

The description is compact and front-loaded with the core purpose before usage and parameter guidance. It contains minor redundancy with the schema's repository parameter description, but every sentence adds practical value and there is no irrelevant 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 read-only listing operation with one required parameter, the description covers the main things an agent needs: what the tool does, when to use it, how to obtain a valid repository identifier, and a warning against inventing values. It does not explain output details or pagination, but given the schema's response_format and limit/offset defaults, the description is reasonably complete.

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 description reinforces the key repository parameter by explaining that id or name from openl_list_repositories() is accepted and is case-insensitive, but this largely repeats what the schema already states. Limit and offset have no description in the schema and are not addressed in the description, so the 50% schema coverage gap is not fully compensated.

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 ('List all Git branch names') and a concrete resource ('a repository'), making the core purpose clear. It also gives a use case ('before switching or comparing versions'), but it does not explicitly differentiate itself from sibling tools like openl_list_project_branches.

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

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

The description gives clear when-to-use context: to see available branches before switching or comparing versions. It also provides a prerequisite workflow: call openl_list_repositories() first if the repository value is not already in context. It does not mention alternatives or when not to use this tool, but the guidance is otherwise strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is established. The description adds useful behavioral context by specifying the 'active' state, 'production environments' scope, and the returned fields, which 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 a single, front-loaded sentence that states the action, scope, optional filters, and return contents without any filler. Every clause adds information, and no space is wasted on redundant phrasing.

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 list tool with five optional parameters and no required inputs, the description covers the main operational need: what it lists, how it can be filtered, and what the result contains. It does not mention ordering or pagination explicitly, but the schema documents limit/offset defaults and the annotations cover safety, making the description adequate.

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 describes project, repository, and response_format, but leaves limit and offset without semantic descriptions. The tool description adds clarity by calling repository a 'production repository ID' and project a 'deployed project name,' but it does not compensate for the missing pagination semantics beyond what the schema already supplies.

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 ('List active deployments'), defines the scope ('across production environments'), and names the two optional filters. It also states what is returned ('deployment names, repositories, and deployed project revisions'), which clearly separates it from sibling tools like openl_list_repositories or openl_list_deploy_repositories.

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: when the agent needs active production deployments, optionally filtered by repository or project. It does not explicitly exclude alternatives or name sibling tools for comparison, but the scope and optional filters make the intended use obvious.

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

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

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful output detail by stating it returns names, types, and status, but it does not disclose pagination behavior or how 'all' interacts with the limit/offset parameters.

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 contain all essential information with no filler. The first sentence states the action and output; the second sentence provides the use case. Everything present 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 what the tool does, what it returns, and when to use it, which is adequate for a simple read-only list tool. However, it omits pagination semantics, does not disambiguate from sibling tools like list_deployments or list_repositories, and has no output schema, leaving some gaps for an agent deciding how 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 only 33%, with limit and offset lacking descriptions in the schema. The tool description does not mention any parameters or compensate for this gap, leaving pagination semantics and response format options unexplained despite the tool claiming to list all repositories.

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

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

The description states a specific verb and resource: 'List all deployment repositories in OpenL Studio' and enumerates the returned content (repository names, types, and status). This distinguishes it from siblings like list_deployments or list_repositories by name, although it does not explicitly name or contrast those alternatives.

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 phrase 'Use this to discover all available deployment repositories before deploying projects' provides a clear use context. However, it does not mention when not to use it or how it compares to similar tools such as openl_list_repositories or openl_list_deployments.

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 provide readOnlyHint and idempotentHint, and the description adds complementary behavioral detail: it never returns bodies, never calls OpenL Studio, embeds docs at a specific release tag, and explains the meaning of the two entry types. This goes well beyond annotation defaults without contradicting them.

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

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

The description is dense but efficient, front-loading the most decision-relevant fact (metadata only, use openl_get_guides for bodies) before explaining entry categories and filtering. Every clause adds useful information; nothing is filler.

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

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

Despite lacking an output schema, the description specifies the exact metadata fields returned, explains the content categories, covers filtering and pagination, names the companion tool for bodies, and notes the local read-only nature. This is complete enough for an agent to select and invoke the tool correctly.

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

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

The description adds meaningful parameter context beyond the schema: it clarifies what 'type' values represent, that 'search' is case-insensitive over id and title, and that results are paginated via limit/offset. It does not describe response_format, but the schema already provides a solid enum description for 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 action ('List'), a clear resource ('OpenL reference documentation bundled with this server'), and an explicit scope ('METADATA ONLY') that distinguishes it immediately from openl_get_guides. It also names the sibling for retrieving bodies, removing 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 explicitly directs agents to use openl_get_guides when bodies are needed, establishes this as the metadata-browsing entry point, and clarifies filtering and pagination behavior. It also notes the tool is read-only and local, giving clear context for when it is appropriate to invoke.

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 openWorldHint=true, covering the safety profile. The description adds workflow context beyond those annotations: correct results depend on a preceding call to openl_list_project_modules, and outputs are meant to feed table creation/copying operations. No contradiction exists between the 'List' verb and the read-only 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 zero filler. The core purpose is front-loaded in the first sentence, and the second sentence packs both the prerequisite call and the downstream usage into one efficient clause. Every word 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 tool with 2 required parameters, full schema coverage, and strong annotations, the description covers the full usage arc: what it returns (worksheet names), how to prepare inputs (exact moduleName from a prior call), and what to do with results (destination sheet for create/copy operations). The lack of an output schema is mitigated because the description implies the return shape. Minor gaps remain around error behavior or handling of invalid module names, but these are not critical for a read-only listing 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%, with rich inline guidance: projectId must be used 'without modification or reformatting' and moduleName must be 'exactly as returned by openl_list_project_modules().' The description's mention of calling openl_list_project_modules first mostly reinforces what the schema already says, adding marginal value. Baseline 3 is appropriate when the schema carries the parameter 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 opens with a specific verb plus resource: 'List worksheet names in a project module.' This cleanly distinguishes it from sibling tools like openl_list_project_modules (lists modules, not sheets) and openl_list_tables (lists tables). The title 'List Module Worksheets' reinforces the same scope without 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 explicit sequencing context: 'First call openl_list_project_modules to get the exact moduleName' states the precondition, and 'Use a returned sheet name as the destination sheet when creating or copying a table' states the downstream purpose. It does not name alternatives to avoid or explicit when-not conditions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, and the description adds meaningful safety context beyond those flags: it explains the two scope behaviors, the meaning of base/protected flags, and the consequences for deletion. There is no contradiction between the description and annotations.

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

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

The description is dense but every sentence earns its place: core purpose, scope semantics, deletion safety, merge workflow usage, and sibling differentiation. It is efficiently structured with the most important information 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?

For a read-only listing tool with 3 parameters and no output schema, the description covers all essential operational context: what it lists, what the two scopes mean, safety flags, and how it relates to nearby merge/delete tools. The response_format parameter is already fully documented in the schema, so no additional description is needed.

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 goes further by explaining the practical semantics of scope values: project scope returns branches that 'already hold the project' and are 'candidates for switching or deletion,' while repository scope is for discovering otherBranch values before merge operations. This adds decision-relevant meaning beyond the raw enum 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 verb and resource: 'List branch metadata in the repository that hosts a project, including repository base and protected flags.' It also explicitly differentiates from openl_list_branches by calling this tool 'project-aware and returns safety metadata,' so an agent can distinguish it from siblings even before comparing 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 routing guidance: use repository scope to 'discover otherBranch values before openl_check_project_merge or openl_merge_project_branches,' and inspect flags before deletion because the base branch cannot be deleted while protected branches require force and confirmation. It also contrasts with openl_list_branches, making the choice between tools 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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable context beyond the annotations: it specifies the output contents, the session-based project context, and the no-projectId behavior, plus the open-project requirement. It does not describe failure behavior when the project is not open, but that is a minor gap given the explicit prerequisite.

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 first states what it does, the second states what it returns, and the third delivers the prerequisite and caveat. The key constraints are front-loaded in a Note marker, making them easy to spot.

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

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

For a simple read-only list operation with one optional parameter and no output schema, the description is complete: it states the returned item fields, the session-based context, the prerequisite, and the local-repository limitation. An agent has everything it needs to select and invoke the tool correctly.

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

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

Schema description coverage is 100%: the only parameter, response_format, is fully documented in the schema. The description adds meaning by explicitly stating there is no projectId and that the tool uses session-based project context, which helps an agent understand why the parameter list is just one optional format choice. This exceeds the baseline for full schema coverage.

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 ('List local change history for a project') and enumerates the return fields (versions, authors, timestamps, comments), which clearly distinguishes it from sibling operations like openl_restore_project_local_change. It is immediately obvious what the tool does and how it differs from the related mutation tool.

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 a prerequisite ('Requires the project to be opened (openl_open_project first)') and an exclusion ('not available for repository 'local''), giving clear guidance on when this tool is valid. It does not explicitly contrast this list operation with the sibling restore tool or other history-related commands, stopping just short of full when-not/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 cover readOnlyHint and idempotentHint, so the safety profile is established. The description adds that the result includes module identifiers and rules-root information intended for subsequent operations, which is useful behavioral context beyond what 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 sentences with no filler. The primary action and output contents are front-loaded, followed by one sentence of downstream guidance that 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?

With no output schema, the description compensates by listing the return fields and explaining how to use the returned names downstream. It is sufficient for a simple read-only list operation, though exact response structure and edge cases like empty projects are not described.

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 projectId and response_format have detailed descriptions, including where projectId comes from and the available response formats. The tool description adds no parameter-specific detail beyond this, so it meets the baseline without exceeding 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 opens with a clear verb and resource: 'List the modules declared by a project.' It further enumerates the returned contents (module names, rules-root paths/patterns, and modules matched by a pattern), making the tool's scope concrete and distinguishable from sibling tools like openl_list_module_sheets or openl_list_tables.

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 provides concrete downstream use cases: 'Use the returned name when creating/copying a table, selecting a module graph, or listing worksheets.' This gives clear context for when this tool matters, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already indicate read-only, idempotent, and open-world behavior. The description goes well beyond that by explaining pagination mechanics (has_more/next_offset), response contents, local-only project limitations (open/save/close fail, table/rule/test work), the exactness of projectId, and the required workflow with openl_list_repositories(). No contradiction 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?

The description is longer than average but densely packed with necessary caveats: pagination, repository filter pitfalls, local-only behavior, and projectId handling. It is front-loaded with the core purpose and then builds logically through operational details. It could be tightened, but every sentence earns relevance given the tool's complexity.

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 no output schema, the description compensates by summarizing returned fields (project names, status, metadata, projectId) and fully specifying the pagination protocol. It also covers edge cases like local-only projects and the proper way to obtain repository values. Minor gaps remain, such as not enumerating the full status set and not detailing the effect of each include expansion, so it is strong but not exhaustive.

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

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

Schema description coverage is high (83%), but the description's repository guidance directly contradicts the schema: it claims 'Pass either the id or name from openl_list_repositories() — both are accepted', while the schema explicitly says to use the display name and NOT the ID. This is actively misleading for a key parameter. The description does add useful pagination semantics and client-side local filtering, but the contradiction undermines parameter reliability.

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 ('List projects') and enumerates the filtering dimensions, returning fields, and the projectId convenience field. It explicitly states the tool's role ('Use this to discover and filter projects'), setting it apart from sibling list tools that target repositories, deployments, or branches. No ambiguity about 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 gives clear when-to-use guidance ('Use this to discover and filter projects') and provides detailed operational conditions: paginate until has_more is false, do not pass repository filter 'local' for local-only projects, and call openl_list_repositories() first for valid repository values. It does not explicitly contrast this tool with close siblings like openl_get_project, but the intended use is nonetheless 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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral detail about case-insensitive id/name acceptance and the short-token format of actual values, which goes beyond annotations. No contradiction exists.

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

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

Four sentences, each carrying useful information: purpose, return fields, usage guidance, and a warning against invented values. It could be slightly tightened by merging the 'name' guidance with the id/name acceptance sentence, but there is no filler.

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

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

For a simple list tool with zero required parameters and no output schema, the description provides enough return-value semantics and practical guidance. It lacks explicit contrast with sibling list tools and does not mention pagination behavior, but those are minor for this straightforward operation.

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 only 33%, with only response_format documented. The description does not clarify limit, offset, or how response_format affects output. Since low schema coverage requires more compensation from the description, this gap is significant.

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

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

The description states a specific verb and resource: 'List all design repositories in OpenL Studio.' It also clarifies the returned fields ('id' and 'name') and gives concrete value examples, making the tool's purpose unambiguous and distinct from sibling tools like openl_list_deploy_repositories.

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 useful operational guidance, such as preferring the 'name' field and never inventing repository values. However, it does not explicitly state when to use this tool instead of alternatives like openl_list_deploy_repositories, leaving tool-selection partly to inference.

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

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

Annotations already establish readOnlyHint and idempotentHint, so the safety profile is covered elsewhere. The description adds behavioral value beyond them: it discloses that the tool accepts id or name case-insensitively and, consistent with openWorldHint, warns agents not to fabricate values and to obtain them from openl_list_repositories() first. No contradiction with 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?

Four short sentences, front-loaded with purpose and followed by usage, parameter, and workflow guidance in decreasing order of importance. Minor redundancy: sentence 3 largely repeats repository-parameter details already present in the schema, but the overall length stays appropriate and every sentence serves a distinct 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?

For a simple read-only tool with two parameters, no output schema, and no nested objects, the description covers purpose, when to use it, parameter semantics, and the prerequisite workflow. The one gap is that it doesn't describe the shape of the returned feature list, but the tool name and examples make the return content reasonably predictable.

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

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

Schema description coverage is 100% — the repository parameter already documents id/name acceptance, case-insensitivity, and the anti-invention warning in full, and response_format has a complete enum with per-value explanations. The description restates this guidance in prose rather than adding new meaning, so the baseline 3 for high-coverage schemas 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 a specific verb and resource: 'Get features supported by a design repository,' with concrete examples ('branching, searchable, etc.'). This clearly distinguishes it from sibling tools like openl_list_repositories (which lists repositories themselves) and openl_list_branches (which lists branches) — this tool targets repository capabilities, not the repositories or their branches.

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

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

Gives an explicit triggering condition: use it to check feature support 'before performing operations that depend on those features.' It also names the prerequisite call, openl_list_repositories(), and instructs calling it first when the value is not in context. However, it does not name sibling alternatives to prefer instead, stopping short of a full when-not/else statement.

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

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

Annotations already mark this as read-only, open-world, and idempotent, lowering the bar for behavioral disclosure. The description adds useful context beyond those annotations by specifying what the response will contain: value type, multiplicity, and allowed enum values.

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 carry the full purpose, the tableType decision rule, and the output contents with no filler. The most important scoping instruction is front-loaded and directly actionable.

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 no output schema, the description appropriately explains the return value shape. It covers the key usage distinction for tableType and relies on the schema for parameter details. It could go slightly further by noting behavior for invalid or unknown table kinds, but current coverage is strong.

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

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

Schema coverage is 100%, so the schema already documents all three parameters thoroughly. The description restates the tableType behavior already present in the schema description, adding little new semantic value beyond confirming the tool's output contents.

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 'List' with a clear resource: properties allowed in a requested table context. It names the decisive distinction between omitting tableType for Properties-table entries versus providing a public table kind, which separates this tool from all sibling list 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, actionable context on when to omit versus provide tableType, which effectively tells the agent how to select the correct request scope. It does not explicitly name alternatives, but this tool has a unique purpose among the siblings, so the lack of exclusions is not a significant gap.

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 readOnly/openWorld/idempotent, and the description adds substantial behavior beyond that: pagination default/max and loop semantics, tableId-as-id-field mapping, and the warning that table IDs go stale after update/append operations. 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?

Four dense sentences are front-loaded with the core purpose, then move logically through pagination, output usage, and a critical staleness warning. Every sentence earns its place, and the IMPORTANT cue highlights the highest-risk behavior.

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

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

With no output schema, the description covers the essential return guidance: pagination fields, tableId presence and meaning, and downstream tool requirements. Combined with annotations for safety/idempotence and a detailed input schema, 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 description coverage is 71%, and the schema already documents kind, name, limit, offset, projectId, properties, and response_format. The description's mention of filters and pagination defaults mostly restates schema facts rather than adding new parameter-level meaning, though the exact projectId emphasis is useful context.

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

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

States a specific verb ('List') and resource ('tables/rules in a project') with optional filters, clearly identifying it as the inventory operation among table-related siblings such as get_table, update_table, and delete_table. It also signals its role as the source of tableId values needed by downstream table 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?

Gives clear usage context: optional filters, explicit pagination loop with has_more/next_offset, and the need to re-list after edits that change table IDs. It does not explicitly contrast against a single-table getter, so it falls just short of naming 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?

Goes far beyond what destructiveHint/openWorldHint already provide: discloses the repeated precheck, the no-write short-circuit on up-to-date, precheck's inability to predict conflicts, the read-only session-bound conflict state, the force/confirmForce coupling, and the explicit prohibition on auto-resolving conflicts. This is extensive behavioral disclosure that meaningfully reduces agent surprise. No contradiction with the annotations — the 'attempt' language and destructiveHint are consistent.

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?

Approximately 150 words and dense, but every sentence earns its place given the destructive, two-mode, conflict-lifecycle complexity. Front-loaded correctly: purpose first, then precheck behavior, then mode semantics, then conflict handling, then guardrails. Slightly long, yet the length is commensurate with the operational risk the tool carries.

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

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

Despite high complexity (6 params, two modes, conflict lifecycle, force bypass) and no output schema, the description covers precheck outcomes, the status='conflicts' result, and the conflict-state lifecycle well. However, it never enumerates the other status values an agent may receive (e.g., what a successful merge returns), and no output schema exists to fill that gap — leaving agents to guess at the full response shape for round-tripping.

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 with the schema doing the heavy lifting. The description adds genuine value on top: clarifies the directionality of mode ('receive merges otherBranch into the current branch; send merges the current branch into otherBranch'), tightens force semantics to 'eligible protected-target bypass' with confirmForce coupling, and explains conflict-state consequences of an allowed attempt. Slight redundancy with schema text, but the enrichment justified a 4.

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

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

Opens with 'Attempt to merge project branches' — a specific verb plus resource, with the 'attempt' qualifier accurately signaling open-world failure. The description distinguishes this from sibling conflict-inspection tools (openl_get_merge_conflicts, openl_read_merge_conflict_file, openl_cancel_merge_conflicts) by centering on the merge execution itself and the conflict state it creates.

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 strong when-to-use guidance: precheck short-circuits (up-to-date returns without a write, permission/lock blockers fail early), force is reserved for protected-target bypass with confirmForce=true, and the explicit guardrail 'Never choose OURS or THEIRS automatically.' The one gap is that conflict inspection and cancellation are described generically ('inspect it on this same MCP server... cancel the pending state') rather than naming the sibling tools openl_get_merge_conflicts, openl_read_merge_conflict_file, and openl_cancel_merge_conflicts.

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 sparse annotations (openWorldHint, idempotentHint) by disclosing that the top-left value is retained, that a relocating edit changes the location-derived id, and that the response returns the current tableId plus previousTableId when changed. It also explains the recompile trigger for openl_project_status and defines the 0-based coordinate semantics for header and label columns. 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?

Every sentence carries an operational fact: action, constraint, raw-source scope, indexing, id volatility, and recompile behavior. The description is longer than average but front-loads the core action and then layers necessary caveats; there is no filler or repeated schema boilerplate.

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 no output schema, the description explicitly states what the response contains (current tableId, previousTableId when changed) and why it matters for subsequent calls. It also covers the side effect on openl_project_status and the range validity constraint, so an agent has what it needs to call the tool and interpret its result. Minor omissions like error behavior are secondary given the detailed schema.

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

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

Schema description coverage is 100%, so all parameters are individually documented; the description adds value by clarifying the coordinate frame (row 0 = header, column 0 = leading labels) and the validity condition that the range must cover more than one cell. It also reinforces the volatile tableId behavior that the schema already partially states.

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: 'Merge a rectangular range of cells into one in a table's raw source.' It states the top-left value retention behavior and the validity constraints, and it distinguishes the tool from siblings like openl_unmerge_table_cells and openl_update_table_cell by emphasizing the RAW source and any-table-type applicability.

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 the tool is intended for raw-source merging and notes it works for any table type, but it never names alternative tools or states when to prefer this over openl_update_table_range or openl_update_table_cell. There are no explicit when-not-to-use conditions, leaving the agent to infer routing from the sibling list.

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 generic openWorldHint annotation, the description discloses the key side effects: automatic creation of intermediate folders, deletion of the source file, HTTP 409 on collision, and staging in the working copy requiring a later commit. This is substantial transparency for a mutation tool and matches the 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?

Five short sentences front-load the action and then pack in endpoint, side effects, and error behavior. It is dense but not padded; only the endpoint mapping is arguably optional.

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

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

Covers operation semantics, failure mode (409), staging workflow, and branch handling, which is complete for a focused move/rename tool. The absence of an output schema means response shape is not described, but the response_format parameter and simple operation mitigate that 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?

All parameters have rich schema descriptions, so the description carries no extra burden. It reinforces branch pinning and intermediate folder creation, but adds no new parameter semantics 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?

States a specific operation ('Move or rename a file within a project') with concrete resource paths and endpoint. The 'source file is deleted after the move' detail differentiates it from sibling openl_copy_project_file, while rename/relocate language separates it from write/delete 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?

Gives explicit intended use—'Use this to rename a file or relocate it to another folder'—and identifies the follow-up commit with openl_save_project. It does not explicitly contrast with copy/write/delete siblings, but the side-effect description ('source file is deleted') makes the choice 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?

The annotations only provide openWorldHint, so the description carries most of the behavioral burden. It does communicate that opening is a preparatory/editing action and that revision mode is for viewing, but it does not disclose side effects such as whether the currently open project is replaced, whether resources are locked, or what state the project enters.

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 concise sentences, each earning its place: core action, branch/revision capability, and workflow placement. No filler or redundant restatement of structured fields.

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?

No output schema exists, yet the description does not explain what the tool returns or what 'opening' changes in the current work context. The required parameter, branch/revision modes, and suggested usage are present, making it operable, but the stateful behavior and return semantics remain under-specified.

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

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

Schema coverage is 100%, and all parameters have clear descriptions, so the baseline is 3. The main description adds a high-level branch/revision framing but does not materially enrich the parameter semantics beyond what the schema already 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?

States a specific verb and resource: 'Open a project for editing.' The description also distinguishes the tool from read-only alternatives by emphasizing it is the prerequisite before changing tables or rules, and by contrasting branch-based editing with Git revision viewing.

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

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

Gives explicit when-to-use guidance: 'Use this before making changes to project tables or rules.' It does not name sibling alternatives or state 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?

Discloses non-obvious side effects: branch switching before validation, lazy compilation start when idle, waiting on a live status topic, progress notifications, 409 on wait=false branch mismatch, and timeout fallback. This goes well beyond the annotations' readOnlyHint=false and idempotentHint=true, giving the agent an accurate model of when the tool mutates state.

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: purpose first, then default/wait behavior, then the read-only exception, then the recompilation note. Every sentence carries a distinct fact needed to call the tool safely, with no redundant 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?

For a tool with no output schema, the description names what it returns (compile state, diagnostics, pending changes, module/test summary) and the key terminal states (ok/warnings/errors). The schema fills in per-parameter details like timeout and severity. It could further describe the exact response shape or failure modes for unopened projects, but overall it is sufficient for correct invocation.

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

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

Schema description coverage is 100% and the parameter descriptions are already detailed, covering wait semantics, branch mismatch behavior, severity sorting, timeout caps, and response formats. The main description's extra behavioral notes add useful context but do not materially improve parameter understanding beyond what the schema already documents. 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: it returns compile state, diagnostics, pending changes, and module/test summary. This clearly differentiates it from sibling tools like openl_get_project or openl_get_test_results_summary, which cover only subsets of that status surface. Very little inference is needed.

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 direction: default wait=true behavior, 'Set wait=false only for a fast read-only snapshot', and 'Omit for repositories that do not support branches'. It also notes that table edits already trigger recompilation. It does not name sibling alternatives for when to prefer openl_get_test_results_summary or openl_list_project_local_changes, so I won't give full marks.

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 openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context: backend download behavior (whole file downloaded before client-side slice), byte-length targeting with potential +3 UTF-8 bytes, nextOffset continuation semantics, and chunked return format. It also clarifies the read-only nature for manual resolution, going beyond the annotations.

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

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

The description is dense but organized: core purpose first, then behavioral constraints, then return format details, then parameter semantics. Every sentence adds information; there is no filler. It is longer than the typical tool description, but the complexity of chunked reads, encoding variants, and side selection justifies the length. The front-loading of the read-only/manual-resolution constraint is effective.

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 no output schema, the description covers the return envelope (MIME, byte-range, nextOffset, hasMore), the side semantics, the file-path provenance, and the encoding forms. It doesn't explicitly document the exact JSON envelope field names beyond nextOffset, but the output is client-side and an agent can infer the structure. Given the 7 parameters and chunked-read complexity, the description is nearly complete, with only minor room for more explicit output-field 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 coverage is 100%, so the schema itself documents all 7 parameters thoroughly. The description adds value by explaining the byte-length semantics (up to 3 extra UTF-8 bytes), the continuation pattern via nextOffset, and the default encoding behavior. The description's mention of 'JSON text envelope with MIME and byte-range metadata' complements the response_format parameter. The file path provenance from openl_get_merge_conflicts also reinforces the file parameter's 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 clearly states the tool reads one BASE, OURS, or THEIRS version of a conflicted file as read-only evidence for manual resolution. It explicitly says it never infers or applies a winning side automatically, distinguishing it from merge-resolution tools. The exact file path source is named (openl_get_merge_conflicts), 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 instructs to use the exact file path from openl_get_merge_conflicts and frames this as evidence for manual user resolution, implying it should not be used to auto-apply changes. While it doesn't name specific alternative tools for applying resolutions, the behavioral constraint 'Never infer or apply a winning side automatically' provides clear when-not-to-use guidance. The explicit file-path sourcing also removes ambiguity about which conflict to read.

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?

Discloses substantial behavior beyond the readOnly/idempotent annotations: byte ranges are applied client-side AFTER fetching the whole file because the backend does not support partial transfers, full-file base64 can exceed MCP message limits, and byte-offset boundaries inside multi-byte UTF-8 characters decode to U+FFFD at the seam. It also documents the encoding auto-detect JSON envelope, metadata view, folder listing modes, and ZIP download behavior. 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?

Long but justified for 16 parameters and four distinct behavior modes; the purpose and endpoint are front-loaded and the numbered behavior modes make it scannable. Every sentence earns its place — there is no filler, and the critical memory/byte-range caveat is positioned before the closing use-case 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?

With no output schema, the description carries the return-value burden and covers the main shapes: verbatim UTF-8 text, base64 JSON envelope with byte and MIME metadata, metadata JSON (name, size, extension, lastModified), folder listings, and ZIP envelopes. Version/branch behavior and the MCP message-limit hazard are also covered, leaving no critical gap an agent would need to guess at.

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 coordinating semantics beyond individual parameter docs: how encoding behaves for file vs folder paths, that offset/length bounds the returned size after a full fetch, and the chunked-read strategy for large files. This clarifies parameter interplay that the schema's per-field descriptions do not convey.

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

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

States a specific verb and resource — 'Read any file in a project by its project-relative path' — and maps to a concrete endpoint (GET /projects/{projectId}/files/{path}). It distinguishes itself from the write/delete/search/copy/move project-file siblings by enumerating its full scope: file content, folder listings, metadata, and ZIP downloads.

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

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

Gives explicit when-to-use guidance ('Use this to read AGENTS.md, README.md, schemas, manifests, or to inspect/export xlsx rule files') that makes intended use concrete. It does not explicitly name exclusions or say 'use X instead for Y', so differentiation from alternatives rests on the read-only scope, the endpoint mapping, and sibling names rather than an explicit routing statement.

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

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

Annotations only carry openWorldHint, not a readOnly or destructive hint, so the description must disclose side effects. It says 'redeploy' and 'update/rollback,' but does not say whether the existing deployment is replaced in place, whether the same deployment ID remains valid, or what happens to the previous version.

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, no filler, with the core action front-loaded before the use cases. Every sentence contributes.

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 simple schema and full parameter descriptions, the definition is mostly sufficient. However, there is no version parameter, so an agent may need to know how the 'new project version' is selected or whether the project must be saved/published first; the description leaves that implicit.

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 each parameter already has a meaningful description, so the bar is met by the schema. The description adds no parameter-level details, which is acceptable at the baseline.

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

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

Opens with a specific verb+object: 'Redeploy an existing deployment with a new project version.' The second sentence makes the scoped use cases explicit (update to newer version, rollback to previous), and 'existing deployment' distinguishes it from deploy-style siblings like openl_deploy_project.

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