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

The description reinforces and clarifies the annotations: 'It modifies no files: apply the returned plan yourself' explains why readOnlyHint/destructiveHint=false hold for a tool whose name contains 'add'. It also enumerates what gets returned (instructions, manifest additions, templates), which goes beyond the annotation set.

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 purpose and followed by return contents and the no-write constraint. No filler or 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?

With no output schema, the description carries the burden of describing return values, and it does so (step-by-step instructions, manifest additions, reference templates). Safety is covered by annotations and the explicit no-write statement. Only per-parameter clarifications are 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 67% and the description adds no parameter-level detail. The 'feature surface' wording loosely echoes the feature enum but supplies no extra meaning for projectPath or framework beyond what the schema already encodes.

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: 'Plan a new feature surface for an existing extension.' That is clearly distinct from extension_build/extension_create in intent, though it never names a sibling explicitly. An agent can tell what the tool produces (a plan, not a build).

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 'for an existing extension' implies usage scope versus creation tools, and 'apply the returned plan yourself' tells the agent what to do next. However, there is no explicit when-not or named alternative (e.g., extension_templates, extension_build) 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/idempotent/non-destructive/closed-world, but the description adds genuinely new behavioral context: it is static only, reads dist/<browser> from the filesystem, never touches a browser, and therefore must be preceded by a build. That workflow prerequisite and scope boundary go well beyond the structured annotations.

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

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

Three sentences, front-loaded with what is analyzed and what it outputs, then the static-only constraint, then the sibling alternative. No filler and each 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?

No output schema exists, and the description compensates by listing the concrete outputs (sizes, entry points, permissions, bundle composition, store-readiness checks). Combined with the readOnly annotations and the build-first prerequisite, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 67% and the description adds little: it references 'dist/<browser>' which loosely maps to the browser parameter, but the format enum values (summary/tree/json) carry no description in either schema or prose. With the schema doing most of the work and coverage above the midpoint, a baseline 3 is appropriate.

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

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

States a specific verb (analyze) against a precise resource (a BUILT extension on disk) and enumerates exactly what is reported: file sizes, entry points, permissions, bundle composition, and store-readiness. It also explicitly differentiates from the sibling extension_inspect, so an agent can pick between them without opening a schema.

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

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

Gives an explicit prerequisite ('build first with extension_build') and an explicit alternative plus its selection condition ('Use extension_inspect for a running extension's live DOM and console'). Both the when-to-use and the when-not-to-use path are 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?

Annotations declare the safety profile (non-readonly, idempotent, non-destructive), so the bar is lower, and the description adds genuinely new behavioral context: every check returns pass/fail/inconclusive, and inconclusive is never a pass. It does not disclose failure or timeout behavior of the overall run, which keeps it short of a 5.

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

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

Three sentences, each doing work: what it does, what the verdicts mean, and how to start/sidestep. The purpose is front-loaded and 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?

With no output schema, the description carries the return semantics and does so adequately by defining the three verdict states and the inconclusive caveat. Prerequisite session state is also covered, so an agent can call it correctly.

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

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

Schema coverage is 100% and the schema itself enumerates the check ids, their args, browser defaults, and the route-dependent timeout values. The prose adds no parameter meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Run a test stage against a live dev session') and clarifies the output shape ('one verdict for each' expectation). It explicitly separates itself from extension_inspect and extension_logs, which return raw readings.

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 prerequisites ('Start the session with extension_dev') and names the alternatives to use when a raw reading is wanted rather than a verdict. It also frames the when-to-use case: assertions instead of hand-rolling judgement over a blob.

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 give a coarse destructiveHint=true/openWorldHint=true; the description supplies the real behavioral detail: status never returns the token, logout deletes credentials locally while the server token stays valid until revoked, tokens are capped at 7 days server-side, GitHub federation happens server-side so no GitHub token lands locally, and server verdict can downgrade a local login to refused-by-server.

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 purpose and organized in action order (status, login, logout, multi-login, projects), and nearly every clause carries load-bearing detail. It is, however, a single dense ~350-word paragraph with some redundant restatement, which costs it the top mark.

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, and the description compensates fully by naming returned fields and their semantics (value.server.verdict with confirmed/refused/unavailable, status logged-in/refused-by-server, `logins`). Everything an agent needs to call and interpret this tool 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 already 80% and its per-parameter descriptions are detailed, so this is largely the baseline-3 territory; the description nonetheless adds genuine semantics the schema lacks, notably the two-phase login/deviceCode resume flow and the `projects`-instead-of-`project` exclusivity rule.

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?

Starts with a specific verb+resource ('Sign this machine in to extension.dev, report that login, or clear it') and then enumerates the three action modes with distinct behaviors. An agent can distinguish it from every sibling (auth vs build/preview/publish) without opening the schema.

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

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

Explicitly states when to use each action (status as default read, login two-phase with project/deviceCode, logout local-only) and names alternatives: `projects` versus `project` with the constraint 'Pass it instead of `project`, never beside it.' It also routes to the console URL for re-minting CI tokens.

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 (destructive/openWorld/idempotent=false), the description disambiguates which action is destructive and its blast radius ('uninstall... never touches a system install'), and warns that install is a several-hundred-MB blocking call requiring a generous client timeout. That is exactly the operational context the structured hints cannot convey.

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

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

Four dense sentences, front-loaded with the overall purpose and default action, then one sentence per action. No filler; the timeout warning and uninstall-safety note are placed where they are 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 still tells the agent what detect and list return (binary path, version, engine, debugger support; cache sizes) and what install/uninstall do to disk. Combined with the annotations and a four-parameter schema, nothing essential for a correct call is missing.

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

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

The schema documents 75% of parameters, but the 'action' enum itself carries no per-value description in the schema, so the description's explanation of each action and the stated default meaningfully extends it. It also confirms browser is required for install and that browsers limits the detect scan (omit to check all), though it says nothing about the 'all' uninstall flag beyond what schema already covers.

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 concrete verb set and resource ('Find, install and remove the browsers Extension.js tooling can launch') and then breaks the tool into four named actions, so the agent knows exactly what it operates on. It never references a sibling, though, so mapping this against launch-oriented siblings like extension_start is left to inference.

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?

Each enum value is paired with the condition that selects it and its return shape: detect (default) scans system + managed and reports path/version/engine/debugger support; list shows cached downloads with sizes; install fetches a managed binary; uninstall removes managed binaries. Requirements (browser is required for install) and exclusions ('never touches a system install') are both 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 mark this as a non-readonly but non-destructive, idempotent, closed-world operation; the description adds real behavioral context beyond that: where output lands, that validation failures block the build and why, that skipValidation can yield a broken bundle, and that Safari builds convert to a macOS app.

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

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

Four sentences, front-loaded with the core action and output location, and each sentence carries distinct information rather than padding. The bundleId sentence is dense but earns its length given the collision warning.

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 13-param, no-output-schema tool, the description covers the highest-stakes behaviors (validation gating, Safari/Xcode path, store packaging) and leaves the low-stakes flags to the thorough schema. Adequate, though a note on return values or build-output differences would round it out.

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 92%, so the baseline is 3, but the prose adds meaning beyond the schema: it explains the collision risk of omitting bundleId (shared generated dev.extensionjs.* identifier) and the exact consequence of skipValidation. It does not cover the remaining params (mode, silent, polyfill, forceRegenerate) in prose, so it isn't a full 5.

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

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

States a specific verb+resource+"for production" scope, immediately distinguishing it from sibling build-adjacent tools like extension_dev. An agent knows this produces a production bundle rather than running a dev server.

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 conditional guidance for the flags that matter (zip:true for store packaging, skipValidation:true to bypass the validation refusal, browser:'safari' for Xcode conversion). It does not explicitly name a sibling alternative or state when NOT to build, so it stops short of the 5 bar.

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

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

Annotations already declare non-read-only, non-idempotent, open-world and non-destructive behavior, yet the description adds real side-effect detail beyond them: git repository initialization with a first commit, store metadata and a self-authored .gitignore. This is exactly the kind of disclosure that annotations cannot convey. It still omits failure/overwrite behavior, so not a 5.

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

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

Front-loaded with purpose, then ordered instructions, then behavioral caveats, in four dense but non-redundant sentences. The final sentence is long but carries the readback contract, so every clause 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 scaffolding mutation with no output schema, the description covers prerequisite, side effects, and how to read back applied defaults. It is largely complete; the notable gap is behavior on an existing target directory or failure, which the non-idempotent annotation hints at but the description never explains.

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 baseline is 3; the schema already documents each parameter including parentDir's cwd caveat and aliases. The description's defaultsApplied note concerns output readback rather than parameter meaning, so it does not add much beyond the schema.

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

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

States a specific verb and resource: 'Create a browser extension project from a template in the extension.dev catalog.' An agent immediately knows this scaffolds a project. However, the description never distinguishes itself from the sibling extension_project_create, which is an apparent overlap it should address.

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 gives a prerequisite and ordering: 'Call extension_templates first to see what is available.' That routes the agent correctly before invoking. It stops short of stating when-not to use it (e.g. versus extension_project_create) or what happens if the target directory already exists.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's value is the extra behavioral context it adds: the exclusive unlock of the allowControl/allowEval channels, the implication chain (allowEval implies allowControl), the 0600 session token, and the fact that the result carries process info needed by extension_wait/extension_inspect. It does not restate annotation claims, and it adds real coupling semantics that structured fields do not convey.

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

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

Front-loaded with the primary purpose, then the disambiguating alternative, then the dependency semantics. Each sentence carries distinct 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 16-parameter, non-idempotent start tool with no output schema, the description supplies the missing pieces: when to use vs alternatives, what channels it uniquely enables, and what the result feeds into. Enough for correct invocation without further documentation.

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

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

Schema description coverage is 94%, so the schema does the heavy lifting and baseline would be 3. The description adds value by explaining the allowControl/allowEval relationship in terms of which sibling tools consume each flag, clarifying why an agent would set them rather than just what they do.

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 ('run the extension while you edit it') and enumerates the core capabilities: dev build, HMR, browser with extension loaded. It explicitly distinguishes itself from the sibling extension_start (production build), so an agent can pick between the two without opening either schema.

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

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

Gives an explicit trigger ('Reach for this first when the ask is "run my extension"'), names the disambiguating alternative (extension_start for production), and states the downstream conditions this tool satisfies (it is the only tool that unlocks the control and eval channels required by extension_storage, extension_reload, extension_open, extension_dom_snapshot, and extension_eval). Nothing 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is low, and the description still adds two useful facts beyond them: the tool is free and requires no login. It also discloses the response shape (pages plus excerpts), though no pagination behavior is mentioned.

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 purpose leads and the usage guidance follows. Every clause is load-bearing.

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 signals the return format (pages with excerpts), and for a free read-only search it covers cost, auth, and when to call. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including defaults, bounds, and the platform-override URL. The description only restates the keyword-based lookup, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Find) and resource (pages in the Extension.js and extension.dev docs), plus the return shape ('each with a short excerpt'). It is the only documentation-search tool among siblings, so no disambiguation ambiguity remains.

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

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

Gives an explicit trigger: 'Use it before answering from memory on anything version-specific,' with three concrete examples (CLI flag, cross-browser manifest field, store submission rule). No alternative tool is named, but none exists for this capability, so the guidance is effectively complete.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds real behavioral context: the per-leg {check, status, detail, remediation?} return shape, dependency ordering, that 'skip' means blocked rather than pass, and that a no-allowControl session returns ok:true with status 'read-only' instead of erroring. This is substantive disclosure beyond structured fields.

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 scope, then the return shape, then the two key behavioral caveats, then the usage triggers. Dense but every clause earns its place; only slight length pressure keeps it from a 5.

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

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

No output schema exists, but the description specifies the return shape (one {check, status, detail, remediation?} per leg) and the non-error read-only outcome, so an agent knows both what it will get and how to interpret it. Complete for a zero-required-param diagnostic tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's param-relevant statements (browser defaults to the active session, omit projectPath for pre-flight) largely restate what the schema already documents, adding little syntax or format detail beyond it.

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

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

States a specific verb (diagnose) and resource (dev session) and enumerates the exact legs checked (ready contract, dev-server process, control-port agreement, control channel, eval token, executor, browser liveness). This clearly separates it from the sibling act tools like extension_eval, extension_reload, and extension_storage.

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

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

Explicit when-to-use: 'Run this first when any act tool (storage, reload, eval, open) errors unexpectedly.' Also gives a distinct invocation mode: 'Call it with no projectPath for a pre-flight environment check.' Both the trigger and the alternative usage path are named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful behavior: localhost-only, the snapshot needs no CDP but listTargets and tabUrl resolution do need the debug port, and the ambiguity policy (candidates returned instead of guessing). It does not describe pagination or output shape, but adds substantial context beyond the annotations.

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

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

The core purpose is front-loaded, but the description is a dense run-on with nested parentheticals and backtick-heavy clause chains that slow comprehension. Every sentence carries information, yet the structure is not cleanly parsable.

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 read tool with no output schema, the description sketches the return payload (element counts, extension roots, open shadow roots, optional byte-capped HTML, console lines) and covers the discovery paths, prerequisites, and exclusions. Only minor gaps remain, such as return shape details for the enumeration modes.

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 92%, so the schema does most of the work and baseline is 3. The description nevertheless adds meaning beyond the schema: html is byte-capped, listTabs/listTargets ignore the other args and return a specific shape, tabUrl resolution order (live browser, substring, titles fallback). That is more than restating field 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?

Opens with a specific verb+resource ('Take a shallow structured DOM snapshot of one chosen surface') and immediately positions itself as the unique 'SURFACE PICKER' that reads open extension surfaces by name and is the only tool taking a numeric chrome.tabs id. It also names what it is unlike (extension_inspect), so an agent can differentiate it from all 30 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?

Explicitly states when to use it (reading an open surface by context name, enumerating what is open via listTargets/listTabs) and when not to (it does not pierce closed shadow roots, run selector probes, or navigate — use extension_inspect for those). It also gives a prerequisite: start the session with allowControl:true.

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?

Despite annotations already declaring destructive/openWorld/non-idempotent, the description adds substantial context beyond them: the 0600 session-token gate, that debug-port evaluates run with a user gesture so gesture-gated APIs behave differently, the CDP vs in-bundle relay routing, and the Firefox debugger-protocol fallback for eval-forbidding CSPs. That is exactly the behavioral detail 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 purpose and the eval-disabled gate are strongly front-loaded, and most clauses carry genuine routing information. It does run long and dense, bundling many edge cases into a single block, so it is efficient but not maximally tight.

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

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

For a 7-parameter, multi-route tool with no output schema, it covers prerequisites, context resolution, timeouts, and surface/tab addressing thoroughly. It stops short of describing the returned result shape or error formats, but the operational guidance needed to invoke it correctly is nearly 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?

Schema description coverage is 100%, so each parameter is already documented, including the context default, timeout defaults, and url-vs-tab precedence. The description largely restates those defaults rather than adding syntax or format meaning beyond the schema, so baseline 3 applies.

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

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

The opening sentence gives a precise verb+resource: 'Evaluate an expression in a running extension context.' It immediately names the prerequisite tool (extension_dev with allowEval:true) and cooperates with extension_open and extension_dom_snapshot, leaving no ambiguity about what this tool does versus its 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?

It states explicit when/when-not conditions: start the session with allowEval:true, otherwise every route answers eval-disabled; use extension_open before targeting a surface; pass url or tab to disambiguate content/page; context:'page' for the active tab. Alternatives and prerequisites are spelled out rather than 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?

With annotations covering the safety profile, the description still adds substantial behavioral context: it navigates the tab to `url` before reading, it cannot address an extension surface by name or accept a chrome.tabs id, and it lays out engine-specific requirements (bridge evals blocked by Firefox MV3 CSP, console replay needing engine 4.0.15+). This is exactly the auth/permission and side-effect disclosure the annotations don't carry.

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?

Purpose, exclusivity, and sibling routing are front-loaded in the first three sentences, and nearly every clause carries actionable information. It is dense and one unbroken paragraph, though, which makes the browser-matrix tail harder to parse than it needs to be.

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

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

For a 7-parameter tool with no output schema and complex cross-browser execution paths, the description supplies the missing context an agent needs: session prerequisites, what each browser can and cannot do, which shadow roots the default reads cross, and how probe output is shaped. Nothing essential to invoking it correctly is omitted.

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 prose largely restates what the schema already documents for `url`, `probe`, `deepDom`, and `include` (its deepDom browser notes closely mirror the schema text), adding little semantic detail beyond the structured fields.

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 ('Inspect a running extension deeply over the browser's debugger protocol') and enumerates exactly what is read: full HTML, DOM structure, content-script injection, console messages, and CSS selector probes. It explicitly differentiates from siblings ('This is the ONLY tool that pierces closed shadow roots...') and names extension_dom_snapshot and extension_analyze as the alternatives for adjacent jobs.

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

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

It states when to use each alternative ('Use extension_dom_snapshot to choose which tab... Use extension_analyze for a built extension's files on disk') and the gating precondition ('requires an active dev or start session'). It further gives per-browser conditions (Chromium needs the session's debug port, not allowControl; Firefox needs allowEval:true; deepDom needs an MV2 session with host permissions).

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), yet the description adds substantial behavior: Chromium's requirement of at least one live context, dormant MV3 service workers being absent until woken, the Firefox RDP listAddons mechanism and engine-version floor, and the temporaryInstallation marker. It also assures the agent that other extensions' contexts are never attached to or evaluated in, which is real scope 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?

The purpose and returned fields are front-loaded, and the browser-specific caveats follow in logical order with no filler sentences. It is dense and slightly run-on in places, but every sentence 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?

With no output schema, the description carries the burden of describing results and does so: returned fields, the ownExtension flag, the temporarilyInstalled marker, and per-browser context presence. The session prerequisite and cross-browser divergence are both covered, leaving no gap 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 100%, so both parameters (browser, projectPath) are already documented in structured form. The description reinforces the session requirement but adds no new syntax, format, or defaulting detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the extensions in the running dev browser') and enumerates the returned fields (id, name, version, live contexts), which clearly separates it from siblings like extension_browsers or extension_inspect. The per-browser framing further pins down exactly what gets listed.

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

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

Gives a clear precondition ('This requires an active dev or start session') and explains when entries appear differently on Chromium vs Firefox. It stops short of naming sibling alternatives or stating when not to use this tool, so it is strong context without explicit 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?

Goes well beyond the annotations by disclosing that this reads the agent-bridge plane used by the `extension logs` CLI, that one-shot reads logs.ndjson, that follow replays a broker ring of up to 5,000 events (counted in value.replayed) then live frames during followMs (value.live), and that an active dev session is required. This is rich operational context an agent needs.

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

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

Three dense but front-loaded sentences; the core purpose leads and mode specifics follow. Every sentence carries information, though the middle sentence is heavy with 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?

For an 11-parameter tool with no output schema, the description covers the prerequisite session, both operational modes, and the shape of returned counts (replayed/live). It misses only explicit return-format details for one-shot reads, which is minor given the strong annotation coverage.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by explaining follow's replay/live split, the value.replayed and value.live outputs, and the followMs collection window. This enriches the follow and followMs parameters beyond their schema entries.

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 or stream logs') and resource ('logs from every context of a running dev session'), and enumerates the contexts explicitly. An agent can distinguish this from sibling tools like extension_inspect or extension_dev 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?

It clearly explains the two modes (one-shot file read vs follow:true live channel) and states the prerequisite of an active extension_dev session. It lacks explicit when-not-to-use guidance or direct comparison to sibling tools, but the mode selection context 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral substance beyond that: the four categories of findings it produces and the existence of a buildBlocking field that determines whether a build is refused. It does not mention severity levels, whether validation is fast/offline, or how findings are ordered, which keeps it out of 5 territory.

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 core action and scope, followed by the finding categories and then the downstream consequence. Nothing is redundant and the most decision-relevant clause ('across browsers') appears 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?

With no output schema, the description compensates by naming buildBlocking and the categories of findings an agent should expect. That is enough to call it correctly, but it does not sketch the overall result shape (e.g. per-browser grouping or pass/fail summary), leaving a small gap for a tool with an entirely undocumented return value.

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 all four parameters (browser, browsers, projectPath, manifestPath) carry their own descriptions, including the aliasing relationship between browser and browsers and the projectPath/manifestPath substitution. The description text adds nothing about parameters, so the baseline of 3 is correct.

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 ('Validate a manifest.json') and immediately scopes it ('across browsers'), then enumerates the exact defect classes it surfaces (missing fields, invalid permissions, dangling file references, cross-browser issues). This is distinguishable from siblings like extension_build, extension_doctor, and extension_analyze without opening any schema.

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

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

It gives a clear operative context by tying itself to extension_build ('the errors that make extension_build refuse') and pointing at the buildBlocking field, which tells an agent this is the pre-build gate. It stops short of explicit when-not guidance, e.g. why to choose this over extension_doctor or extension_analyze, so it falls one step short of a 5.

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

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

Goes well beyond the annotations: it discloses Chromium-only sidebar fallback via synthetic click and tab rendering, the warnings channel, CDP Target.openDevTools usage, that action/command replay runs without a user gesture so activeTab does not apply, and that reload discards page state. This is exactly the extra side-effect and caveat context annotations do not carry.

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 is front-loaded and each sentence conveys substantive behavioral detail rather than filler, but it is a single dense run-on block with heavy parenthetical asides that would read better as a per-surface breakdown. Appropriately sized for nine surfaces, slightly overpacked in 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?

For an 11-parameter tool with no output schema it covers the main intents, prerequisites, and fallback behaviors well, and even hints at the return shape for the devtools case. It is largely self-sufficient, though the return framing for the non-devtools surfaces is left 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: how `url` interacts with `tab`, that `panel` selects among multiple panels, and that the devtools result url is consumed by extension_eval with context 'page'. That linking value lifts it 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?

States a specific verb (open/replay) and resource (extension surface or event) and enumerates every surface value with its distinct effect. It also names related siblings (extension_dev for the allowControl session, extension_eval for reading the panel document), so an agent can place it precisely in the toolset.

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

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

It tells the agent which surface value to pass for each intent (UI surface vs chrome_url_overrides tab vs DevTools vs action/command replay) and gives a prerequisite (start the session with allowControl:true). It lacks explicit when-not-to-use guidance against alternatives like extension_reload or extension_inspect, 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 only declare the generic safety profile (writes, open-world, non-idempotent); the description adds substantial behavioral context beyond them: sharing uploads and hands over built code, is metered against a plan allowance, requires a scoped token or yields a login hint, is live until share.expiresAt, revocation is permanent, and each share is logged to a gitignored file. This is well past the bar set by 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?

Purpose and the no-real-browser qualifier are front-loaded, and the sentences are dense with decision-relevant information rather than filler. It is long for a single paragraph, and a couple of clauses (e.g. the gitignore log detail) border on optional, 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?

With 10 parameters, no output schema, and an open-world network write, the description does the heavy lifting: it names the returned fields an agent must inspect (share, share.previewUrl, share.zipUrl, share.expiresAt, share.revokeUrl, deepLink) and covers auth and cleanup. A tighter mapping of the default-lane result shape would make it fully 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?

Schema description coverage is 100% and the parameter descriptions are themselves extremely detailed, so the schema already carries the parameter burden. The body text adds nuance about the share/build interaction but largely restates what the schema properties say. Baseline 3 is appropriate.

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

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

States a specific verb and resource (preview an in-progress extension in a web emulator) and immediately scopes it against alternatives: 'with no real browser,' the share lane vs. the local deep-link lane. An agent can distinguish it from extension_dev, extension_start and extension_build without opening any schema.

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

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

Explicitly tells the agent when to pass share:true and when not to ('unless you are working inside the extension.dev monorepo'), explains which lane works from an npm install, and names extension_shares as the revocation path. When/when-not/alternative are all present.

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

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

Goes well past the annotations: two-phase device-code approval flow, a provisioning grant that lives minutes, can create only the named project, and is never stored locally, plus project + mirror-repo creation, first-build dispatch with a `firstBuild` reason field, and server-memory-only grant retention for batches. Rate/lifecycle limits (10 per approval, 10 per hour, next batch after the hour allows) are disclosed, which annotations cannot convey.

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

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

Purpose and sequencing are front-loaded, and most sentences carry routing or behavioral information. It is long (~400 words) and restates the 10-per-approval cap twice across the batch paragraph, so it could be tightened, but there is little pure 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 complex 13-parameter, nested-object, no-output-schema creation tool, the description covers the two-phase protocol, the return shape (`firstBuild` status/reason, one row per project with created/no-token/refused/not-attempted), and failure modes (connect link, batch refusal on unsupported platforms). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents each parameter. The description adds cross-parameter semantics the schema cannot: `projects` substituting for `project`+`repo`, sharing top-level inputs as defaults, the 1–10 cap, and that `deviceCode` is reused until every listed project has an answer. It is additive rather than redundant.

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 and resource ('Create an extension.dev project for an extension that does not have one yet, without opening the console') and immediately distinguishes itself from three siblings (extension_create, extension_build, extension_auth). An agent can identify exactly what this does and when it applies 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?

Explicit sequencing: 'Use it right after extension_create and extension_build, once the extension's source is pushed to a GitHub repository, and BEFORE extension_auth', with the reason extension_auth cannot create the project. It also states the follow-up (extension_publish) and the batch alternative, so when-to-use and what-comes-next are both pinned down.

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?

Despite annotations covering the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description adds substantial non-obvious behavior: the target is the token's project with no projectPath and no local file upload, public projects get a canonical URL where ttlHours is ignored while private ones get a time-limited ?share= link, and buildSha is an unverified platform claim the platform may echo back on a failed build. These are real gotchas that annotations cannot express.

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

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

Front-loaded with verb, target and return value, then threading the alternative path, token precedence, and public/private URL semantics in order of relevance. The prose is dense and every sentence carries information, though the final paragraph is long enough that a reader must parse carefully.

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, and the description compensates by explaining the return value in both cases (canonical public URL vs fresh ?share= link with ttlHours lifetime). It also covers the auth model, multi-login disambiguation, and the buildSha verification caveat, which is everything needed to call a four-parameter, zero-required deploy 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 already 100%, so the schema fully documents api, project, buildSha and ttlHours. The description's parameter-relevant content (project precedence over EXTENSION_DEV_TOKEN, ttlHours ignored for public projects, absence of a projectPath) largely restates the schema rather than extending it, so the baseline 3 applies.

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

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

States a specific verb and resource ('Publish the project your stored token is scoped to ... to extension.dev') and names the concrete artifact returned (shareable URL). It also explicitly distinguishes itself from the sibling extension_submit by labeling that tool the 'separate store-review path', so an agent can route without opening either schema.

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

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

Gives the when-to-use framing directly ('This is what "deploy" or "ship" an extension usually means') and names the alternative path (extension_submit) with the condition that selects it. It further states prerequisites for the multi-login case (pass `project`, which outranks EXTENSION_DEV_TOKEN), leaving little 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?

Goes well beyond annotations by disclosing auth mechanisms (stored login or EXTENSION_DEV_TOKEN), the 7-day token lifetime and CI re-mint requirement, the human approval gate two-call flow, and that promotion is not reversible in place. The status semantics ('promoted', 'promoted-partially', 'promote-unconfirmed') add real operational 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?

Front-loaded with the write/auth/safety facts and generally dense with useful content, but it is long and some status-handling detail could be trimmed. Nearly every sentence carries weight, so it stays efficient despite its size.

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 nine parameters and no output schema, the description supplies the missing return semantics (status values), auth requirements, approval flow, and irreversibility. Nothing an agent needs to call it correctly appears absent.

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

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

Schema coverage is 100% and its field descriptions already cover approvalId's two-step flow, project precedence, browsers fallback, and buildId format. The description largely restates this, so it adds little parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('promote a built extension to a release channel') and explicitly claims unique scope: 'the only verb that changes what a channel points at.' It is clearly distinguishable from siblings like extension_publish, extension_release_status, and extension_build.

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 routes the agent: 'Call extension_release_status to find a valid buildId,' and names the exclusion ('Cutting a version-bump PR is not available headlessly'). It also states the recovery conditions for partial and unconfirmed outcomes.

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/destructiveHint=false, but the description adds real value beyond them: 'dispatches nothing and promotes nothing', the caveat that registry state can lag store dashboards, and that private projects work when the stored login covers them. This is strong disclosure, though return-shape detail leans on the include explanation.

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

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

Front-loaded with purpose then default behavior, section semantics, overrides, and caveats. Dense and information-rich; each sentence carries weight, though the middle is somewhat packed and could be split for easier scanning.

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 does so: it describes the release channels, build URLs, and per-store fields (configured state, credential health, last submission, review status) plus their source files. An agent has enough to call and interpret 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 coverage is 100% (baseline 3), and the description adds meaning beyond the schema by enumerating what include:'releases' returns (channel→promoted sha, builds, build-page URL) and include:'stores' returns per store. It also clarifies workspace/project override the stored login default.

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 where a project stands on extension.dev, from the public registry (registry.extension.land).' It clearly positions itself as a status/read tool distinct from the mutation siblings it references.

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

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

Explicitly tells the agent when to use include:'releases' (to find a valid sha for extension_release_promote, extension_submit, extension_publish) and include:'stores' (after extension_submit). It names the alternative tools and the conditions that route to them rather than leaving it 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 non-read-only, idempotent, non-destructive behavior, and the description is consistent with them. It adds the session-control prerequisite (allowControl:true), which is useful behavioral context, but does not say what reload resets (background state, tab contents) or what auth/session it depends on beyond that.

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 zero waste; the core action is front-loaded and the prerequisite follows immediately. Nothing is padded or redundant.

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

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

For a state-changing tool with no output schema, the description conveys the action and the session requirement but leaves the effect of the reload and any return signal unstated. Annotations carry some of the safety burden, so it is 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 high (80%) and the timeout/browser/projectPath params are well documented in-schema. The description's 'background context, or a tab' loosely maps to the context and tab parameters but adds no format or selection detail beyond the schema. Baseline 3 when 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?

States a specific verb (reload) and resource (a running extension's background context, or a tab), which cleanly separates it from siblings like extension_build, extension_start, and extension_stop. It doesn't explicitly name those siblings, but the action 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?

Provides a genuine precondition — the session must be started with allowControl:true via extension_dev — which tells the agent when this tool is callable. It stops short of saying when to prefer this over alternatives such as extension_start or restarting the session.

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 readOnlyHint=false, the description adds substantial context beyond them: revoke is permanent and cannot be undone, the platform's approval gate requires a two-step human workflow, projectPath is read-only, and the append-only local record is never rewritten. It also discloses the 429/503 failure mode that answers listed-local-only.

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 the default action are front-loaded, and the density is largely justified because there is no output schema and the field enumeration must live in the description. It is still a single very long block, and some return-value detail could be tightened.

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, open-world tool with nine parameters, no output schema, and no required parameters, the description compensates fully: it enumerates the returned fields, explains attribution.ownership and attribution.credit semantics, clarifies which server.* counters are share counts, and states the token requirement.

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 meaning above that baseline by framing approvalId as part of a two-step revoke workflow and explaining that status:'all' exists specifically to make a dead link explainable, though much of the surrounding detail concerns return fields rather than 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 opening sentence names a specific verb pair and resource ('List and revoke the public preview links this token has shared') and directly distinguishes itself from the sibling that creates these links ('which is what extension_preview_web share:true hands out'). An agent can identify the tool's role 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?

It explicitly walks through when to use action:'list' versus action:'revoke', when approvalId is required, when projectPath reconciliation applies, and which token is needed (extension_auth or EXTENSION_DEV_TOKEN). It even names the fallback behavior when no token exists, leaving nothing 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?

Goes well beyond the annotations by disclosing that there is no HMR and no control channel, enumerating exactly which sibling tools cannot attach (extension_eval, extension_storage, extension_reload, extension_open, extension_dom_snapshot), and explaining that a noBrowser production start ends when the build does.

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 purpose and free of filler, but the long multi-clause sentence chain is dense. Every clause does convey distinct behavior, so little is wasted.

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

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

For a 14-parameter launch tool with no output schema, the description covers build/serve/launch mechanics, session limitations, and the prebuilt-artifact path, which is everything an agent needs to invoke it correctly.

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

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

Schema coverage is 93%, so the baseline is 3, but the description adds cross-parameter behavior: outputPath 'implies build:false' and build:false serves an existing dist or fails when none exists. That relational meaning is not in the schema itself.

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 ('Run the PRODUCTION build in a browser: build the project, serve it, and launch') and explicitly distinguishes itself from the sibling extension_dev, so an agent can route correctly without opening schemas.

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

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

Gives explicit when-to-use routing ('Use extension_dev while writing code, and this to check what actually ships') plus concrete conditional variants for build:false and outputPath. Alternatives and exclusions are named directly.

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 carry destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description still earns credit by specifying exactly what is destroyed (server + launched browser + live-preview carrier) and the preview-session edge case. It does not address failure behavior when no session exists, leaving a small gap.

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 primary action and scoped by three tight sentences with no filler. The first sentence is dense but every clause (server, browser, carrier) carries distinct information. Slightly heavy for its length, but no sentence is wasted.

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

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

For a destructive lifecycle tool with no output schema and thorough annotations, the description covers purpose, scope of destruction, the preview-session variant, and the usage trigger. It omits the no-op/error case when no session is found, which is the only notable missing context.

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 docs are unusually thorough (all, browser, projectPath, includeOtherServers). The description adds no parameter-level syntax or format detail beyond what the schema states, so the baseline 3 is appropriate when 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?

Specific verb (stop) plus resource (session) and an explicit enumeration of what is terminated: the server, the launched browser, and the live-preview carrier. It names the sibling tools that create these sessions (extension_dev, extension_start) and even calls out the extension_start build:false preview variant, so an agent can distinguish it from launcher tools without opening any schema.

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

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

Gives a clear triggering condition: 'Call it when you are done verifying, so sessions do not accumulate.' That establishes when to invoke it relative to the dev/start lifecycle. It does not state when *not* to call it (e.g. mid-verification, or while another server owns the session), so it falls short of 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?

Adds substantial behavior the annotations cannot express: every call runs in the background so it proves nothing about content-script or page reads, a set is read back and the answer reports whether the stored value matches, and there is no bulk-object set. These are real operational traits beyond the destructiveHint/non-idempotent flags, and nothing 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?

Dense and front-loaded: purpose first, then behavioral caveats, then setup requirement, then the key-per-call constraint. Every sentence carries information, though the phrasing is compact enough that some clauses read as terse.

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

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

For a 7-parameter tool with 86% schema coverage and no output schema, the description covers the non-obvious behavior well (background execution semantics, read-back verification, session prerequisite). It is nearly complete; only explicit alternative routing is absent.

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

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

Schema coverage is 86%, so the baseline is 3, but the description goes beyond the schema by imposing a genuine usage constraint: 'Set one key per call: there is no bulk-object set,' which clarifies how key/value must be used. It adds meaning on top of the documented 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 opening sentence names a specific verb pair and resource: 'Read or write chrome.storage in a running extension.' It is unambiguous about what the tool operates on. Sibling differentiation is only partial — it references extension_dev for session startup but never explicitly contrasts itself with extension_eval or extension_inspect.

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

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

Gives a concrete prerequisite ('Start the session with allowControl:true (extension_dev)') and a scoping caveat explaining what the call does and does not prove. It stops short of naming an alternative tool or an explicit when-not set of conditions.

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

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

Annotations already declare destructive/non-idempotent/non-readonly/openWorld, and the description builds well past that: dry-run default and exactly which gates it skips vs. the real run, irreversibility, owner-only authorization, the approval loop, draft-upload behavior for Chrome/Edge without a saved mode, the submitted/partially/unconfirmed outcome vocabulary, and the 7-day token expiry. This is unusually rich disclosure for a destructive tool.

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

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

Purpose and the publish-vs-submit distinction are front-loaded, and the dry-run/real-run semantics follow logically. It is a dense, single long paragraph with some redundancy (irreversibility, token expiry and submission-mode checks are restated), but for a tool with this much behavior every clause mostly 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 carries the full burden and does: it describes return-state vocabulary, failure handling ('read extension_release_status before submitting again'), prerequisites (build index, token, owner gate), and irreversible side effects. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100% and each parameter is already well documented, so the baseline is 3. The description adds real meaning beyond the schema: it explains where the project identity comes from (token vs. `project`), how approvalId is used across two calls, that credentials are never arguments, and that projectPath is only used for a local STORE.md advisory.

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 with scope: 'Submit a built extension for store REVIEW through extension.dev'. It explicitly names the sibling it is not (extension_publish) and clarifies that 'deploy' or 'ship' usually means the other tool, so an agent can distinguish them without opening either schema.

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

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

Gives explicit when-to-use ('only when the ask is explicitly a store submission'), when-not ('does not push a build to the platform, does not make a shareable link'), the alternative (extension_publish), and points to extension_release_status for valid shas and post-submission outcome. Nothing 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 this as a safe, idempotent, open-world read, so the bar is lower. The description still adds real context beyond them: 'list' returns metadata per template, 'source' returns a template's files, and it flags a non-obvious interpretation pitfall ('framework is the UI framework only, never the language'). It omits pagination/rate-limit behavior, so not a 5.

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

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

Front-loaded with purpose and the action modes, then the framework caveat, so the most important routing information comes first. The framework sentence is long but every clause carries a distinct slug/tag mapping, so it earns its space; only mild density cost.

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 8 all-optional parameters, no required inputs, and no output schema, the description does the necessary work by explaining both modes and roughly what each returns. It does not describe the file-listing vs file-content return shape in detail, but it is complete enough 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 already 88%, so the baseline is 3, but the description adds genuine meaning the schema lacks: it clarifies that 'framework' is UI-framework-only and that TypeScript/JavaScript, shadcn variants, and provider AIs are reached via slug/tags rather than the framework enum. That disambiguation is exactly what an agent would otherwise get wrong.

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

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

The opening sentence names a specific verb and resource ('Browse the extension.dev template catalog'), then splits that resource into two concrete modes ('list' for search/filter/metadata, 'source' for reading one template's files). An agent can tell what this tool is and what it does 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?

Usage is spelled out per action: 'list' is the default for searching/filtering, and 'source' is for 'learning a pattern before building something similar', which gives a clear motivating context. It stops short of naming sibling alternatives (e.g. extension_docs_search) or when-not-to-use, so it is strong context rather than full 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 readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: it verifies only and never authors or mutates, explains the D1/D3/D4 problem taxonomy (including keys Chrome silently discards), and discloses the headless limitation and that attended legs return needsAttended rather than passed.

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

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

Front-loads the purpose and remains a tight cluster of sentences, each carrying real information about scope, method, and return semantics. It leans heavily on domain jargon (four-leg, D1/D3/D4) that a fresh agent must infer, slightly reducing clarity per unit 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?

With no output schema, the description carries the return-value burden and does so by explaining the classification outputs and the needsAttended/passed distinction. It is nearly complete for an agent to call it correctly, missing only the explicit alternative sibling and any concrete invocation example.

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 both parameters (manifest, manifestPath) are documented in the schema itself. The description adds no additional parameter syntax, format, or precedence detail beyond the schema's own 'pass this or that' guidance, so baseline 3 applies.

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

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

States a specific verb+resource ('Verify a Chrome theme manifest before it ships') and richly characterizes scope: it settles the four-leg WYSIWYG contract headless and classifies problems into D1/D3/D4. The theme-specific framing implicitly distinguishes it from the general extension_manifest_validate sibling, though that sibling is never 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?

Gives clear usage context ('before it ships') and explicitly scopes what it can cover headless versus what needs a browser, routing the app-rendered and real-pixel legs to the assert:theme and install-parity harnesses. It stops short of naming the obvious sibling alternative (extension_manifest_validate) by name.

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

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

Goes well beyond the readOnly/idempotent annotations: it explains the ready.json polling contract, the three reported signals and which one (guestLoaded) to trust, why it can be null, timeout/retry semantics, and port sourcing. This is unusually 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?

Dense but front-loaded: the core purpose leads, followed by signal meaning, null caveat, timeout retry, and noBrowser behavior. Nearly every sentence carries actionable information, though it is on the longer side.

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 naming each returned field and its meaning. Combined with the annotations covering the safety profile, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including the deprecated alias and clamping range. The description adds little parameter-level detail beyond noting ports come from the contract, so the baseline 3 applies.

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

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

States a specific verb+resource: 'Wait for a running dev or start session to be ready.' It clearly positions itself as the waiting/polling tool among siblings like extension_start and extension_dev. An agent can distinguish it immediately.

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

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

Explains the trigger context (a running dev or start session) and instructs to 'call again to keep waiting' on timeout, plus the noBrowser short-circuit. No explicit sibling alternative is named, but the usage condition is clear enough.

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

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

Annotations only say it is a non-read-only, non-idempotent, open-world mutation. The description adds far more: a two-phase approval flow, that the first call returns a code and URL, that a signed-in GitHub user approves and becomes owner, that the grant is short-lived, single-purpose, names no project, and is never stored locally. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with purpose and the sibling relationship, then flows into the two-phase mechanics. It is long, but nearly every sentence (ownership, grant lifetime, next call) carries information an agent needs; only mild trimming is possible.

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

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

For a complex async, auth-gated creation tool with no output schema, the description covers the return values (code, URL, deviceCode, ownerGithubLogin), the sequencing, and the follow-up. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by tying deviceCode to the second call ('call again with the returned deviceCode to finish') and flagging ownerGithubLogin as the ownership signal, adding flow semantics the schema field descriptions do not fully 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 ('Create an extension.dev workspace that does not exist yet, without opening the console') and distinguishes itself from extension_project_create by scope. An agent can tell what it does and when it applies without opening the schema.

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

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

Explicitly orders it before extension_project_create and explains why: 'project creation can only target an existing workspace.' It also notes that personal workspaces already exist, so this is for shared/org-style workspaces, and even prescribes the follow-up call ('run extension_project_create against <workspace>/<project>').

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