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

Annotations declare readOnlyHint=false and destructiveHint=true, but the description adds substantive context the annotations don't: input is treated as untrusted planning data, endpoints are never invoked, and external $refs are not followed. This is meaningful safety information. The mild tension with openWorldHint=true (description insists on local-only, no external resolution) is a narrowing rather than a contradiction, and the description never explains what state is written or what 'catalogs' produces.

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, zero filler, with the capability and the key safety guarantee both front-loaded. Every clause carries information an agent needs.

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 one-parameter import tool with annotations present and no output schema, the description covers formats, trust model, and side-effect boundaries. It leaves out what gets returned or where the cataloged result is stored, which an agent would want before deciding what to do next.

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?

Only one parameter, and schema description coverage is 0% — 'path' has no documented meaning in the schema. The description partially compensates by implying a local file path for one of the listed spec formats, but it doesn't say whether relative or absolute paths are accepted, encoding expectations, or size limits.

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 (import) and resource (API documents) plus the exact accepted formats: OpenAPI/Swagger JSON/YAML, Postman v2, WSDL XML. 'Catalogs operations; never calls endpoints' distinguishes it from the sibling api_document_read and from api_request.

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 'local ... as untrusted planning data' clearly establishes the context of use and implicitly excludes remote fetching or live API interaction. However, it never names the alternative siblings (api_document_read, requirements_import) or states when to prefer them, which would be needed for 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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description adds the non-obvious pagination protocol, telling the agent how to iterate until exhaustion. It does not disclose page shape or whether empty pages can occur mid-stream, and 'nextOffset' does not correspond to any field name in the schema, which may confuse an agent looking for that key.

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, no filler, with the core action and pagination instruction front-loaded ahead of the sibling exclusion. Every sentence carries information the agent needs.

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, three-parameter paged listing with annotations covering the safety profile and no output schema, the description covers purpose, paging, and routing. It is not complete, however, on the required documentId's format and provenance, which is the one thing an agent can get wrong when invoking 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 0%, so the description bears the burden; it only partially compensates by implying limit/offset paging through 'in pages' and 'nextOffset'. It never explains that documentId is a 64-character hex identifier or where that value comes from, leaving the required parameter undocumented in both schema and prose.

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 — 'Read imported API operations and schemas' — rather than restating the tool name, and it distinguishes the scope from prose/PDF content ingested elsewhere. It stops short of naming api_document_import as the producer of the documentId, so the agent must infer where the id originates.

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?

'Requirements/PDF prose use requirements_import instead' is an explicit alternative with the condition that selects it, which is exactly the sibling-routing guidance most definitions lack. It also gives the pagination loop ('Follow nextOffset until null'), though it offers no when-not guidance beyond the prose exclusion.

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

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

With annotations already declaring destructiveHint=true and openWorldHint=true, the description still adds genuinely new behavior: no redirects are followed, non-safe methods require an explicit authorized policy, and secrets should come from env references. It stops short of saying what happens on assertion failure, whether the response body is returned, or what the policy's deniedTargets/redactKeys actually do.

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 with the purpose front-loaded and no filler. The compression goes slightly too far — 'and status/body/schema/timing assertions' is a fragment missing its verb — which costs a point on structure.

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?

This is a complex, destructive, open-world tool with a deeply nested schema, no output schema, and 0% schema documentation, yet the description is three sentences. It omits how step assertions combine, how captures feed later steps, what a failed assertion yields, and what side effects a destructive request can have — all of which an agent needs before calling 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 0%, so the description must carry the parameter burden and largely does not. It mentions the method default and the policy object only in passing, while the entire nested 'step' surface — capture, headers, checks, jsonSchema, maxDurationMs, allowSoapFault, soapAction, soapVersion, path vs target — is never explained anywhere.

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?

Names a specific verb ('Execute') and resource ('one explicit REST/SOAP request') plus the assertion dimensions (status/body/schema/timing), so it is clearly not a document reader like api_document_read nor a database call. It never explicitly contrasts itself with any sibling, so it stays at 4 rather than 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?

'GET/HEAD/OPTIONS by default; supply a user-authorized policy for other methods' tells the agent how to unlock writes, which is real conditional guidance. But there is no statement of when to reach for this tool versus database_query, ui_action, or the api_document_* tools — the tool-selection decision 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?

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds one genuinely new fact — credentials are supplied through named environment variables rather than parameters — which matters for a zero-parameter tool. The 'bounded read checks' clause largely restates readOnlyHint, and the return shape is not 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?

Two sentences with no waste, and the core function (what is listable) is front-loaded ahead of the credential and safety notes. Every clause carries distinct information.

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

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

For a zero-parameter, read-only discovery tool with no output schema, the description covers what is listed, how credentials are sourced, and the read-only scope. The only real gap is that it does not hint at what the returned adapter/driver entries look like, which would help the agent parse results.

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

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

The tool takes no parameters, which is the baseline-4 case. The absence of inputs is consistent with the description's framing of a listing/introspection operation, so nothing further is required.

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: 'List database adapters and locally installed optional drivers.' An agent can distinguish this discovery tool from the sibling database_query without opening a schema. It stops short of naming database_query as the follow-up action, so no explicit sibling differentiation.

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 is implied rather than stated: the mention of credentials via environment variables and 'bounded read checks' signals this is a pre-flight introspection tool. There is no explicit when-to-use, when-not-to-use, or named alternative such as database_query.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful context: requires a read-only account, uses bound parameters rather than interpolated SQL, and records connection/query timing. It does not describe error behavior or rate limits, but the added safety and execution details exceed 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?

Three front-loaded sentences with no redundant restatement of the tool name. Each sentence contributes purpose, safety/account requirements, or execution 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?

For a complex nested database tool with no output schema, the description establishes the high-level contract and safety profile. However, it leaves much of the nested invocation structure (target/step fields, capture, expect.checks) undocumented, so an agent still relies heavily on the raw 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 0% for a deeply nested schema containing target, step, operation, expect, filter, params, capture, and driver/timeout options. The description only hints at operation types, assertions, and bound parameters; it does not explain how these fields map to the schema or what the nested step/target structures require.

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 ('Perform') and concrete resource operations (SQL SELECT, MongoDB find, Redis GET) plus read-only scope. It is clearly distinct from database_capabilities, but does not explicitly name sibling 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 description implies use for bounded read-only queries and notes the read-only account prerequisite, but gives no explicit when-to-use or when-not-to-use guidance. It also does not name alternatives such as database_capabilities.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a meaningful behavioral boundary — that no installation or launch occurs — which prevents the agent from mistaking a diagnostic for a setup action. It stops short of describing what the check reports.

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 short sentences, zero filler. The capability statement is front-loaded and the limiting clause follows immediately, so an agent can parse intent in one pass.

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

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

For a zero-parameter read-only diagnostic with annotations covering safety, the definition is nearly sufficient. The only gap is that, with no output schema present, the description does not hint at what 'capabilities and workspace' returns, so the agent cannot anticipate the 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?

The input schema has zero parameters with additionalProperties=false, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly implies a no-argument invocation.

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

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

The description states a specific verb+resource: 'Check platform capabilities and workspace.' It is clear what the tool inspects, though it does not explicitly differentiate itself from the related sibling database_capabilities or explain what 'doctor' means beyond this sentence.

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?

One exclusion is given ('Does not install or launch anything'), which implies a diagnostic/preflight usage, but there is no explicit statement of when to call it versus siblings like database_capabilities or ui_ux_check. The agent must infer that this is the first-call health check.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds real context the agent could not otherwise know: a backup and audit log are created, and assertion steps or expected values cannot be modified. That materially scopes the blast radius of a destructive operation. It still omits what the preview returns or what happens when the locator fails.

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, zero filler, with the core action and its preview/persist duality front-loaded. Every sentence carries distinct information (capability, scope limit, verification step).

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 and a rich nested locator schema, the description covers intent and safety but not the shape of a preview result or failure behavior. An agent still doesn't know what 'preview' returns or how to interpret a rejected patch.

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

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

Schema description coverage is 0% across 5 parameters, including a nested locator object with twelve undocumented fields. The description hints at the locator ('locator-only patch') and at the apply flag ('preview or persist'), but leaves path, testId, stepIndex, and every locator strategy field (css/role/text/frame/etc.) unexplained, so it does not compensate for the coverage gap.

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 pair (preview/persist) and resource (a locator-only patch in a suite), which is concrete enough to distinguish it from siblings. It does not explicitly name heal_suggest as the alternative, so sibling differentiation is implied 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?

The preview-vs-persist distinction implies a workflow and the closing line 'Rerun the patched suite to verify' gives post-call guidance. However, it never says when to call this versus heal_suggest, nor when not to use it, so usage must be inferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'does not execute or modify anything' is largely a restatement. The one genuine addition is the failure mode: ambiguous or fuzzy identities yield no automatic repair, which tells the agent to expect empty/absent results rather than guessing. Return shape and how 'real snapshot' is resolved remain undisclosed.

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

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

Two short sentences, front-loaded with the purpose followed by the safety/limitation caveat. Nothing is padded, though the second sentence spends half its length repeating annotation-declared read-only 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?

No output schema exists, so the description must carry the burden of explaining what a suggested repair looks like and how it relates to sessionId and the eleven-field locator. It omits the prerequisite that a snapshot must exist and says nothing about return values, leaving an agent unable to predict output or parameter trade-offs.

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

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

Schema description coverage is 0% and the nested locator object exposes eleven mutually alternative fields (css, role, name, testId, automationId, etc.) with no guidance anywhere. The description never mentions sessionId, the locator object, or which identity fields take precedence, so it compensates for none of the documentation gap.

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 ('Propose') and resource ('selector repairs') plus the mechanism ('exact accessible identities in a real snapshot'). It implicitly contrasts with heal_apply's apply semantics but never names that sibling, so an agent must infer the distinction.

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 'Does not execute or modify anything' clause hints this is the dry-run counterpart to a mutation tool, and the ambiguity caveat hints when it will fail, but neither states when to choose this over heal_apply nor what prerequisite state (e.g. an existing snapshot/session) is needed.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, readOnlyHint=false, so the write/destructive nature is signalled. The description adds that output is written as Markdown and JSON to a path, but does not disclose overwrite behavior, permission needs, or what an existing plan at path is replaced with.

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

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

Three sentences, front-loaded with the purpose then format detail. Dense but every clause maps to a real aspect of the schema; 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 12-parameter, destructively-writing tool with a deep nested policy object and no output schema, the description leaves major areas (policy, target, path/overwrite semantics, risks) unexplained. It covers only a fraction of what an agent needs to call this correctly.

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

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

Schema coverage is 0%, so the description carries the burden. It usefully explains the requirements anyOf (strings of R01 IDs vs objects preserving source clauses/acceptance criteria), and mentions documents, questions, and scenarios. But it omits name, goal, target kinds, path default, risks, sessionId, apiDocuments, and the entire nested policy object.

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: 'Save a host/model-authored test plan as Markdown and JSON.' Clear what the tool produces. It doesn't explicitly distinguish itself from siblings like test_generate or requirements_import, but the artifact (plan) is named.

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

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

No when-to-use guidance, prerequisites, or named alternatives. The agent can't tell from the text when to call plan_create versus test_generate or requirements_import; nothing states ordering or exclusions.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false), so the description's added value is in describing the return artifacts: a summary plus links to offline HTML and raw results. That is genuinely useful behavioral context absent from structured fields, since no output schema exists. It stops short of noting failure behavior when no run/report is present.

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 short sentences with the default behavior front-loaded and the return content second. Nothing is padded, though the word "truthful" is slightly unusual phrasing that could be more concrete (e.g. 'honest about missing results').

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

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

For a single-parameter, non-destructive read tool with no output schema, the description covers the call decision and the shape of the response (summary + links). Gaps are minor: where the directory is resolved relative to, and what happens when no report 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 0% and the single parameter `directory` is undocumented in the schema, but the description supplies its meaning (a report directory) and, crucially, its optional default behavior (omit to get the latest run). Path format or rooting is not stated, which keeps it out of the top band.

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?

Names a specific verb and resource (read a report) and states the two modes: the latest run, or a specified report directory. It also previews what comes back (summary plus links to HTML and raw results), which separates it from siblings like test_status or traceability_get. It does not explicitly name an alternative, but the resource is unambiguous.

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

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

The phrase "the latest run or a specified report directory" implicitly tells the agent to omit the parameter for the newest run and pass it to target a specific one. However, there is no explicit when-to-use guidance relative to sibling tools, no preconditions (e.g. that a run must exist), and no exclusion cases. Usage is inferable but not spelled out.

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 annotations available (readOnlyHint=false, destructiveHint=true), the description carries real weight: it discloses the write side effect (a content-addressed snapshot), the returned value is truncated to the first chunk, the SHA-256 is recorded, and it explicitly warns that source text is data, never tool instructions (prompt-injection defense). It also bounds behavior with 'No OCR or semantic case generation'. None of this is in the annotations or schema.

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

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

Four tight sentences, front-loaded with the extraction verb and resource, then the side effect, then the return behavior, then constraints. Each sentence adds information; nothing is 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?

No output schema exists, so the description's disclosure that only the first chunk is returned and that a snapshot is saved is essential and present. Remaining gaps — snapshot location, chunk size, and how to fetch later chunks — are minor but real for an import/read workflow.

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 single path parameter has 0% schema description coverage, so the description must compensate. 'local ... inside the workspace' does imply the path is workspace-relative, but it never states the expected format, whether it is relative or absolute, or what happens on a missing file — so the gap is only partially closed.

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 ('Extract local .pdf/.docx/.md/.txt requirement text') plus the side effect ('Saves an content-addressed text snapshot'). It is clearly distinguishable from the sibling requirements_read by the word 'Extract' and the supported source formats, though it never names that sibling explicitly.

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

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

The scope exclusion 'No OCR or semantic case generation is performed' implicitly tells the agent not to use this for scanned/image PDFs or for generating test cases, which is genuinely useful. However there is no explicit routing to requirements_read for subsequent chunks, and no statement of prerequisites for the path argument.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description earns credit for two things annotations cannot express: the pagination-completeness contract and the untrusted-data / prompt-injection warning. It still omits what a response contains (text, nextOffset, end-of-stream signal) and any error behavior for a bad documentId.

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, front-loaded with the action, followed by the pagination rule and the safety note. Nothing is padded, though the 'nextOffset' reference names a field that does not exist in this schema and may momentarily confuse the agent about the parameter 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?

There is no output schema, so the description is the only place to explain the return shape, yet it never says what a chunk contains or how end-of-document is signaled beyond the bare mention of nextOffset. Combined with zero parameter documentation, the definition leaves too much to inference for a paginated reader.

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

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

Schema description coverage is 0% for three parameters, so the description must compensate and largely does not. 'nextOffset' is explicitly referenced, implying the offset cursor, but limit (default 12000, max 24000) and documentId (a 64-char hex pattern) are left completely unexplained in the description.

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: reading the next chunk of imported requirement text. An agent can distinguish it from requirements_import (which brings content in) and api_document_read (generic document reading), though it never names those siblings explicitly.

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

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

Gives concrete operational guidance: iterate on nextOffset until null before asserting the document was fully reviewed. It also sets a security rule for the content read. It does not, however, state when to prefer this over requirements_import or api_document_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?

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond that: native attached applications stay open, i.e. the destruction is scoped to the session only. It still doesn't say whether session state/history is lost or whether the close 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?

One short sentence, front-loaded with the action and followed immediately by the most important side-effect caveat. No waste.

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

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

For a one-parameter tool with annotations covering destructiveness and no output schema, this is close to adequate, but the missing link between sessionId and session_start/session_list leaves a real gap for an agent that must supply the id.

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

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

Schema description coverage is 0% for the single parameter sessionId, so the schema contributes nothing beyond type and requiredness. The description does not explain where to obtain a session id (session_start/session_list) or what 'owned' means for that value.

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

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

States a specific verb+resource ('Close an owned session') with the ownership qualifier narrowing scope. It is clearly the counterpart to session_start among siblings, though it never names that sibling explicitly.

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

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

No statement of when to call this versus alternatives, no prerequisites, no note on what happens if the session is already closed or not owned. Usage is only inferable from the verb.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful ownership scope, but says nothing about whether terminated sessions appear, ordering, or result size.

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?

One short sentence with no filler, and the scoping qualifier is placed immediately after the verb. Nothing redundant or 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?

A zero-param read tool with annotations and no output schema needs little, but the description leaves open what a session record contains and whether closed sessions are returned. Minor but real gaps for an agent deciding what the output will include.

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

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

The tool takes zero parameters and the schema is closed (additionalProperties: false), so there is nothing for the description to explain. Baseline 4 applies for a no-parameter tool.

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 ("List sessions") and narrows scope with "owned by this MCP process," which distinguishes it from session_start/session_close. It stops short of naming a sibling or noting whether closed sessions are included.

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?

Enumeration is self-evidently the intent of a list tool, so usage is implied rather than stated. There is no explicit when-to-use, no note on result emptiness, and no reference to the related session_start/session_close siblings.

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

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

Annotations already declare readOnly=false, destructive=true, openWorld=true, so the safety profile is known. The description adds genuinely non-schema context: execution is local ('Runs on this machine') and desktop actions are serialized (a concurrency guarantee). It omits what a started session consumes, whether sessions leak without session_close, and what the call returns.

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, front-loaded sentences with no filler; the launch/attach split comes first and the execution constraints follow. Brevity is close to the failure line given the schema complexity, but nothing is wasted.

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

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

A tool with a single required nested object holding thirteen undocumented options, destructive semantics, and no output schema needs far more than three sentences. An agent gets no idea how to choose a kind/channel/browser combination or what happens to the process afterwards.

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

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

Schema description coverage is 0% across 13 nested target properties, so the description must carry the load. It only gestures at cdpUrl and pid ('CDP endpoint/native PID') and the kind enum, leaving browser, channel, headless, timeoutMs, executable, windowTitle, args and cwd entirely unexplained.

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

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

States specific verbs (launch, attach) and concrete resources (web/Electron/desktop browser, CDP endpoint, native PID), so the operation is unambiguous. It doesn't differentiate itself from siblings like session_list/session_close, but the core purpose is clear.

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?

No guidance on when to use this versus other session tools, no prerequisites, no mention that a session must exist before ui_* or test_run tools are used. Usage is only implied by the name 'session_start'.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, so the write/foreign-effect profile is structured. The description usefully adds that content is validated first and that a portable runner is emitted, but it never says whether an existing file at the destination path is overwritten, what happens when validation fails, or whether plaintext '.test.mjs' is written alongside the suite.

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 tight sentences, front-loaded with the action and outputs, with the assertion requirement as a closing constraint. Nothing is padded, though the assertion sentence could carry more operational detail at the same length.

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

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

Given a very large nested schema, no output schema, and only safety annotations, the description should explain what successful output looks like (paths written, validation errors) and whether repeated calls overwrite prior suites. It covers the what but leaves the caller guessing about failure and overwrite semantics.

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

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

Schema description coverage is 0% across all three top-level parameters, and the description compensates for none of them: `path`, `planPath`, and the shape of `suite` are never explained. The mention of 'host/model-authored cases' gestures at `suite` but gives no format or versioning guidance for the two schemaVersion variants the schema allows.

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

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

States specific verbs (validate, write) and specific artifacts (an executable JSON suite plus a portable .test.mjs runner) plus the input source (host/model-authored cases). An agent can tell this is generation, not execution, so it is distinguishable from test_run, though no sibling is named explicitly.

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

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

There is no when-to-use or when-not-to-use guidance relative to plan_create, test_run, or heal_apply. The only constraint given is that callers must supply explicit assertions, which is a requirement rather than 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?

With destructiveHint=true and openWorldHint=true already declared, the description adds real context: the call is non-blocking, each case receives isolated UI/API sessions with captures shared only within its own steps, and it writes offline HTML artifacts. It does not warn that steps can mutate the target app or database, which is the main risk connoted by the destructive 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 purpose and async contract are front-loaded in the first two sentences, with versioning and output artifacts after. Every sentence carries information, though the middle clause about shared captures is dense and needs a second read.

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 whose schema is a huge undescribed anyOf of v1/v2 suite shapes, the description supplies the essential framing: version semantics, execution model, session isolation, and that results land in HTML files plus test_status. It leaves the agent to reverse-engineer target, policy, and step structure entirely from the schema.

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

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

Schema description coverage is 0%, so the description must compensate. It maps usefully onto the schemaVersion const by explaining what version 2 adds versus version 1's legacy UI behavior, and hints that suites come either from a saved path or inline. However, it never explicitly distinguishes the 'path' parameter from the 'suite' parameter, leaving that mapping to inference.

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 ('Queue a saved suite or inline suite for sequential execution') and immediately clarifies the async contract with 'Returns immediately with jobId; poll test_status.' This separates it cleanly from test_status and test_generate without the agent needing to open any schema.

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

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

The follow-up path is explicit: poll test_status after queuing, and the v1 vs v2 split tells the agent which suite shape to submit. It stops short of stating exclusions, such as when to prefer test_generate or session_start instead of a full queued run.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it works across all lifecycle states and returns a report directory, but omits what happens for an unknown or expired jobId and whether the read is eventually 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?

One front-loaded sentence with no filler and the report-directory payload surfaced early. It is efficient, though efficiency here partly reflects under-specification rather than tight writing.

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 one-parameter read tool with annotations covering safety, this is close to sufficient, but the missing jobId provenance and lack of any return-shape hint leave a real gap given there is no output schema.

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

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

Schema description coverage is 0% and the single required parameter jobId is undocumented in both places. The description never says where a jobId comes from (presumably test_run) or its format, so an agent must infer the entire 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?

States a specific verb (read) and resource (test job) along with the state range it covers (queued/running/finished) and that the report directory is included. It does not explicitly name siblings like test_run or report_get, so differentiation is inferred from the resource name 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?

Usage is implied — poll a job's state after starting it — but the description never says when to prefer this over report_get or test_run, nor when not to use it. No prerequisites are 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 readOnlyHint=true, non-destructive and openWorld, so the safety profile is covered. The description adds genuine interpretation context — unmapped requirements and not-run cases are surfaced explicitly, and mappings do not imply business acceptance — but says nothing about return shape, size, or behavior when the directory is absent.

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, zero filler, with the core read scope front-loaded and the caveat last. Every sentence carries distinct information.

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

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

For a read-only tool with one optional parameter and no output schema, the description covers what is read and the important interpretive limitation. The remaining gap is default behavior when 'directory' is omitted, which is minor but relevant for invocation.

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

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

Schema coverage is 0% for the single 'directory' parameter, so the description must compensate. The phrase 'from a run or generated coverage folder' hints that the path points at such a folder, but it never says the parameter is optional, what the default is, or whether a run identifier is accepted.

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

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

Specific verb ('Read') plus a clearly named resource (requirement-to-case mappings and recorded outcomes) and scope (from a run or generated coverage folder). It does not distinguish itself from likely siblings such as report_get or requirements_read, so an agent must still infer which tool owns traceability vs reporting.

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 is implied by 'from a run or generated coverage folder', so the agent can infer the tool operates on artifacts produced by test_run/coverage generation. There is no explicit when-to-use vs when-not guidance and no named alternative (report_get, requirements_read) to route between.

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=false, destructive=true, and openWorld=true, so the agent knows this is a mutating, open-world tool. The description adds the behavior that ambiguous targets fail, but it does not explain which actions are destructive, what side effects to expect, or whether assertions are safe read operations.

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 and only two sentences, both of which carry useful information. It is concise, though the term 'typed action' is somewhat opaque given the schema's action enum.

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, destructive UI automation tool with a nested step schema, 22 actions, zero schema descriptions, and no output schema, the description is far too sparse. It omits parameter guidance, action semantics, side-effect expectations, and result behavior, leaving most of the tool's usage to inference.

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

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

Schema description coverage is 0%, and the step object has many nested fields, a 22-value action enum, locator variants, timeoutMs, menuPath, and value. The description only hints that selectors must be exact; it does not explain the action values, when value is required, how locator fields differ, or what the top-level sessionId/step relationship means.

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 domain: perform a typed UI action or assertion. It implicitly separates this from sibling tools like ui_snapshot, but it does not explicitly name alternatives or clarify the full action/assertion 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 a useful prerequisite and failure condition: selectors must be exact and come from a live snapshot, and ambiguous targets fail. However, it does not say when to use this instead of ui_snapshot, ui_screenshot, or ui_menus, nor when it should not be used.

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

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

The description adds real behavioral context beyond the annotations: it names the underlying mechanism per platform, states that recursion is "bounded," and reassures that leaf commands are not invoked, which is valuable for a menu-walking tool. It does not reconcile that reassuring read-oriented framing with the annotation profile (readOnlyHint=false, destructiveHint=true), so an agent cannot tell why a discovery call is flagged destructive or what state ExpandCollapse may change.

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 with the core action front-loaded and platform detail following; nothing is padded. The density is high (UIA, ExpandCollapse, leaf commands are specialized jargon) but each clause carries information.

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

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

For a 2-parameter, no-output-schema tool, the description covers the mechanism but not the contract: it never characterizes the returned menu structure, how deep the default traversal goes, or what happens on platforms where menus are only partially exposed. Adequate to attempt a call, thin for interpreting the result.

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

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

Schema description coverage is 0% for both parameters, so the description bears the full burden and largely fails it. "Bounded UIA ExpandCollapse" gestures at the existence of a traversal limit but never explains what depth means, that it defaults to 6 with a max of 12, or what sessionId must identify.

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: "Discover real menus and nested entries," which tells an agent exactly what it retrieves. The three platform-specific clauses (Electron Menu API, native UIA ExpandCollapse, web exposed menu roles) further pin down the scope. It does not, however, differentiate this from the sibling ui_snapshot, which an agent could plausibly pick 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?

"Discover real menus" strongly implies the use case, so the guidance is inferable rather than stated. There is no explicit when-to-use/when-not clause and no reference to alternatives such as ui_snapshot or ui_action for navigating the discovered menus, leaving the agent to infer routing.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered externally. The description adds that output is a PNG inside the workspace, but it does not disclose overwrite behavior, file-write side effects, or session/auth requirements.

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 with no filler, but it is too terse for a destructive file-writing tool. The brevity reflects under-specification rather than optimal sizing.

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 and no parameter descriptions in the schema, the description should compensate by explaining sessionId, path, and file-write behavior. It leaves the required session parameter, optional path default, and overwrite risk unaddressed.

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

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

Schema description coverage is 0%, and the description never names sessionId or path. 'Active target' loosely hints at the session and 'inside the workspace' loosely hints at path, but the required session identifier and default output path remain unexplained.

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 artifact: capture the active target to a PNG inside the workspace. It is clear what the tool produces, but it does not distinguish this from sibling tools like ui_snapshot or clarify exactly what 'active target' means.

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?

There is no guidance on when to use this tool instead of ui_snapshot, ui_action, or other UI tools. It also omits prerequisites, such as needing an active session before calling 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior: the tree is bounded and a 'truncated' marker signals omitted controls, but it does not say what triggers truncation or how depth/maxNodes govern it.

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 compact clauses, front-loaded with what is returned and followed by the truncation caveat; nothing is wasted. It is terse to the edge of under-specification rather than 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?

With no output schema, the description carries the burden of describing the returned structure, yet it only hints at a tree with a truncated flag and never documents any parameter. For a tool an agent must call with a session and depth/node limits, this leaves important 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 0% for three parameters, and the description never mentions sessionId, depth, or maxNodes. The phrase 'bounded tree' loosely gestures at the trimming parameters but gives no semantics for defaults, limits, or the required session handle.

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 the accessible controls/IDs/labels/windows tree. Clearly distinguishable from ui_screenshot (visual capture) or ui_action (mutation), but the description never names or contrasts any sibling explicitly.

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

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

No indication of when to use this instead of ui_screenshot, ui_menus, or ui_ux_check, and no prerequisites such as needing an active session. The agent must infer usage from the sibling list alone.

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

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

Annotations mark the tool as destructive and open-world, but the description never says what it destroys or changes. That is surprising for a check tool, so it may resize the viewport or write baselines. It also says nothing about pass/fail semantics, what is returned, or side effects on the session. The word 'approved' baseline hints at a precondition but is not explained.

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 dense sentences, front-loaded with the four check types, and no wasted words. The brevity comes at the cost of necessary detail.

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

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

This is a complex, multi-mode tool with a nested schema, no output schema, undocumented parameters and an unexplained destructive annotation. The description leaves out the parameter-to-check mapping, the result format, and how assertion failure is reported.

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

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

Schema description coverage is 0% across a nested object with about 15 fields. The description loosely maps 'check' enum values and 'baseline' (PNG). It leaves target, kind='ux', tags, threshold vs maxDiffRatio, maxOverflowPx, minTapTargetPx and maxDurationMs unexplained, including which fields apply to which check type.

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?

It names four concrete check types (axe accessibility, responsive layout, browser performance, PNG visual-baseline) and says they run against an existing web/Electron session. It also notes that native desktop falls back to UIA assertions and screenshots. It does not set itself apart from siblings like ui_screenshot or test_run.

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?

'Existing session' implies session_start must run first, and the native-desktop note hints at which checks apply where. There is no explicit guidance on when to use this instead of test_run, ui_snapshot or ui_screenshot, and no exclusions.

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