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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) by disclosing partial-failure behavior ('A worker that fails is reported in place; the others still return'), the concurrency cap, and a security warning that this launches N unsandboxed agents with N times the prompt-injection surface. This is exactly the kind of 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 the core action, then failure semantics, then the security caveat. Every sentence carries weight, though the SECURITY block leans on an external module note rather than being fully self-contained.

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 parallel-dispatch tool with an output schema (so return shape needn't be explained), the description covers purpose, failure isolation, concurrency, and the key safety constraint. It leaves the exact composition of the 'labelled block' return to the output schema, which is acceptable.

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

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

Schema description coverage is 100% and the schema itself documents tasks, watch, timeout_s and max_concurrency in exhaustive detail, so the description's only added meaning is the concurrency cap reference. Baseline 3 is appropriate given the schema carries the semantic load.

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 SEVERAL tasks IN PARALLEL across ALL backends in a single swarm') and immediately contrasts it with the single-backend siblings like codex_ask / cursor_ask by explaining that each task names its own backend. An agent can distinguish it from the *_ask and preset_swarm tools from the first sentence.

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

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

Makes the use case explicit (many tasks, mixed backends, concurrent execution with a concurrency cap) and adds a clear when-NOT-to-use constraint ('Only use it with trusted prompts on trusted content'). It does not name sibling alternatives such as preset_swarm or the individual backend_ask tools, so the routing is implied rather than 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?

Beyond annotations (readOnlyHint=false, openWorldHint=true), the description adds authentication context (silent-auth via Windows Credential Manager) and the text-return behavior. The plan and watch parameter descriptions go further by disclosing that agy can run shell commands/write files and what plan mode blocks; the only minor gap is that the main description does not itself warn that the default mode may mutate the workspace.

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 main description is four sentences with the core purpose front-loaded, and every sentence adds value: identity, auth, return type, and usage guidance. No filler or repetition of the title.

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

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

Between the main description and the very rich input schema, an agent has everything needed to invoke the tool safely: authentication, default model, return format, side-effect caveats, version requirements, error/raise behavior, and workspace semantics. The output-schema signal covers return-value 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 100% and the parameter descriptions are unusually detailed (plan-mode caveats, model slug rules, JSON-schema behavior, watch, timeout, workspace), so the main description need not add parameter meaning. It does not go beyond the schema here, earning the baseline 3.

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

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

The first sentence names a specific verb and resource ('Ask Antigravity ... a question in a NEW conversation') and adds the concrete identity 'agy CLI, Gemini by default'. It also states the output contract ('Returns the model's final response as text'), which separates it from continuation and status 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 gives explicit placement guidance: 'Good for fast tool-calling and short tasks; for heavier reasoning pick a bigger model or use the host model directly.' The emphasized 'NEW conversation' also tells an agent to reserve this tool for fresh conversations rather than antigravity_continue.

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

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

Annotations already signal mutating, open-world, non-idempotent behavior. The description adds useful behavioral context: the exact conversation id routing, version-dependent behavior on agy 1.1.8+, and the guarantee that it resumes THIS thread even if a separate conversation was started in the same folder. No contradiction with annotations.

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

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

The description is two short, purposeful paragraphs. The first states the core purpose; the second adds a necessary edge-case clarification about global 'most recent' versus the exact conversation thread. Every sentence earns its place with no filler.

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

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

With 100% schema coverage, rich per-parameter descriptions, an output schema, and safety/open-world annotations, the description only needs to disambiguate conversation routing behavior, which it does thoroughly. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and each parameter already has a detailed description, so the tool description does not need to explain parameters. It adds some conceptual context about how workspace maps to the recorded conversation id, but the schema carries the semantic load.

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

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

The description states exactly what the tool does: 'Continue the Antigravity conversation rooted at this workspace' and explains it resumes the exact conversation id recorded for the workspace. This clearly distinguishes it from starting a new ask and from other sibling tools.

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

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

The first sentence frames when to use the tool, and the second paragraph clarifies that it uses the workspace-recorded conversation id rather than agy's global 'most recent', preventing common misuse. It does not explicitly name antigravity_ask as the alternative for starting new conversations, so it stops short of full when/not guidance.

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

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

Beyond annotations (readOnlyHint false, openWorldHint true), the description adds valuable behavioral context: it consumes AI Pro quota, saves the image, returns path/format/size, and notes that the extension may be corrected. It also mentions unsandboxed session and same privileges as other tools.

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

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

The description is concise, with two paragraphs that front-load the main purpose. Every sentence adds essential information (quota, file output, format behavior, security note). No redundancy or fluff.

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

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

The description covers key aspects: output details (path, format, byte size), format selection, execution context (unsandboxed, same privileges), and quota usage. It references a security note from elsewhere. An output schema exists but is not shown; still, the description sufficiently explains return values.

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 description adds minimal extra detail for parameters. It restates that output_path can be absolute/relative and timeout_s default is 240, but these are already in the schema. The format correction note is a minor addition.

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

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

The description clearly states that the tool generates an image using Antigravity (Gemini image model via agy CLI). It distinguishes itself from sibling tools like antigravity_ask (text generation) and antigravity_image_swarm by focusing on single image generation with file saving.

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

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

The description explains the tool's behavior (quota usage, file path return) but does not explicitly state when to use this tool versus alternatives like antigravity_image_swarm. It lacks guidance on appropriate prompts or scenarios.

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

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

The description discloses file extension correction, concurrency limits, timeout, return format (path/format/size/error), and unsandboxed privileges. Annotations provide readOnlyHint and openWorldHint, which are consistent.

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

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

The description is front-loaded with the core purpose, uses brief paragraphs, and avoids fluff. However, it repeats 'like antigravity_image' and could be slightly more streamlined.

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

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

Given the output schema exists, the description sufficiently covers behavioral details, parameter defaults, concurrency, and workspace handling. It is complete for a tool with 6 parameters.

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 descriptions are thorough. The tool description adds little extra beyond what the schema already provides, such as the listing of return values but not parameter-specific details.

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

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

The description clearly states the tool generates several images in parallel, differentiating from antigravity_image. It specifies each prompt runs in an isolated worker, and returns a block listing results. This distinguishes it from siblings.

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

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

The description explains when to use this tool (for parallel image generation) and compares to antigravity_image and antigravity_swarm. However, it does not explicitly state when not to use it or mention alternatives like sequential generation.

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

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

The description adds significant behavioral context beyond the annotations (readOnly, idempotent): it states it spends no AI Pro quota, is a best-effort GitHub check honoring AGY_BRIDGE_NO_UPDATE_CHECK, details how 0% quota per family is reported as a problem, and lists filesystem checks. No contradiction with annotations.

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

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

The description is a dense but well-organized paragraph with the main purpose front-loaded and usage guidance at the end. All details are relevant, though the long clauses and extensive list make it slightly less scannable than optimal.

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

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

Given that an output schema exists, the description thoroughly covers all checks performed, including version-specific behavior, env-var handling, and edge cases like quota exhaustion. The usage guidance completes the picture, making it comprehensive for a no-parameter 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?

The tool has zero parameters, so the schema fully covers parameter semantics (baseline 4). The description adds no parameter-specific details, but none are needed.

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

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

The description opens with 'Report diagnostics for the agy bridge setup', which is a specific verb+resource statement. It distinguishes from sibling status tools (codex_status, copilot_status) by explicitly targeting the agy bridge, and then details the specific checks performed.

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

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

The final sentence provides explicit when-to-use guidance: 'Use this to debug empty or failed responses — or to see if the bridge itself is out of date, or if you are simply out of quota — before spending quota.' This is clear, but it does not name alternative tools or when-not-to-use, so it falls just short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description adds meaningful behavioral details: the tool uses an existing Codex login, returns only the final message read from `--output-last-message`, and does not use stdout scraping. It also hints at potentially heavy execution with 'real code work.' No contradiction with annotations; some safety specifics live in parameter descriptions, but the core behavioral traits are disclosed.

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

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

The description is compact and front-loaded: the first sentence states the core action and session type. Every subsequent sentence earns its place—login prerequisite, output mechanism, use-case guidance, and workspace advice. No filler or repetition of schema content.

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

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

For a tool that launches a coding agent, the description covers the key operational context: new session, login requirement, output retrieval method, suitability for heavy reasoning, and workspace recommendation. An output schema exists, so return-value detail is not required, and the sandbox/window caveats are handled in the parameter descriptions. An agent has enough information to invoke it correctly and set expectations.

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

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

Schema description coverage is 100%, and the schema itself provides rich parameter descriptions (e.g., sandbox policies, watch behavior, timeout). The main description adds a small strategic tip about `workspace` ('Point workspace at a real project dir'), but otherwise does not need to compensate. This matches the baseline for fully documented schemas.

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

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

The description opens with a specific verb-resource pair: 'Ask OpenAI Codex a question or task in a NEW session.' It distinguishes this from siblings by emphasizing 'NEW session,' which clearly separates it from codex_continue and other agent ask tools. The additional context that it uses `codex exec` and returns the final message makes the tool's intent unmistakable.

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

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

The description gives clear context for when to use it: 'suits heavier reasoning and real code work, not just cheap tool-calling.' It also advises pointing `workspace` at a real project directory for context-aware answers. However, it does not explicitly name alternatives or state when not to use it, so it falls just short of full exclusionary guidance.

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

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

The description adds valuable behavioral context beyond annotations: it explains session resumption logic, fallback behavior, and that the session keeps its original sandbox and model. No contradictions with annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true) are present.

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

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

The description is concise, with two short paragraphs. The first sentence front-loads the primary purpose. Every sentence adds value, with no redundant or irrelevant 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?

Given the tool's complexity (4 parameters, 1 required), schema coverage (100%), and the presence of an output schema, the description covers all key aspects: session identification, fallback, behavior after restart, and preservation of original settings. It is complete for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant extra meaning for parameters beyond what is already in the input schema schema. It provides context around workspace defaults and timeout, but these are already described in the schema.

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

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

The description clearly states that the tool continues an existing Codex session, using a specific command (`codex exec resume`). It distinguishes from sibling tools like codex_ask (which starts a session) and codex_status (status check), and explains the fallback behavior for session identification.

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

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

The description explains when to use this tool (after codex_ask, to continue a session) and includes practical details like fallback after server restart. It does not explicitly state when not to use it or mention alternatives, but the context is clear enough for an agent to infer appropriate usage.

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 provide readOnlyHint and idempotentHint, but the description adds valuable context: confirms no quota spent, describes best-effort GitHub check with environment variable, and details each diagnostic check. No contradictions.

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

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

The description is a single paragraph with a clear flow: purpose, detailed checks, usage note. Slightly long but every sentence adds value; could be more concise but remains efficient.

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

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

Given no parameters, rich annotations, and presence of output schema, the description fully explains what the tool does, its side effects (no quota), and when to use it. It covers all behavioral and contextual aspects.

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

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

The input schema has zero parameters with 100% coverage, so description does not need to add parameter details. Baseline score of 4 is appropriate.

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

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

The description clearly states the tool reports diagnostics for the Codex bridge setup, listing specific checks (version, update, PATH, login status, session storage, pinned sessions). It distinguishes from sibling status tools by referencing antigravity_status and focusing on Codex-specific debugging.

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 when to use: 'debug "codex not found" or auth errors before spending quota.' It also implies not to use for other bridges, and notes the tool spends no quota, making it safe to run.

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

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

Annotations indicate readOnlyHint false, openWorldHint true, idempotentHint false. Description adds useful behavioral details: uses existing login, returns stdout from CLI in silent mode, best-effort watch option, and notes sandbox is not a hard boundary. No contradiction.

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

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

Description is front-loaded with the key action and well-structured, though it could be slightly more concise without losing important details.

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

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

Given the tool's complexity (6 params, output schema, siblings), the description covers purpose, usage, parameters, and output. It lacks explicit error handling but is otherwise sufficiently 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?

All 6 parameters have schema descriptions (100% coverage), and the description adds context beyond schema, such as explaining model validation limitations, sandbox distinctions from codex, and workspace usage for context-aware answers.

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

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

The description clearly states 'Ask the GitHub Copilot CLI a question or task in a NEW session,' specifying the verb, resource, and distinguishing from sibling tools like copilot_continue.

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

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

The description advises using the tool for real code/repo work with workspace context, and mentions alternatives like copilot_status for login. It warns about model validation errors, but could more explicitly say when not to use.

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

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

The description reveals behavioral traits beyond annotations: it resumes the exact session ID, falls back to the newest on-disk session, and re-applies permission flags each call. This adds value over the annotations (readOnlyHint=false, openWorldHint=true) which do not specify these details. No contradiction.

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

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

The description is concise with two short paragraphs. The first sentence immediately states the core purpose. The second paragraph adds crucial differentiation without redundancy. Every sentence provides value, and the information is front-loaded.

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

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

Given the tool has an output schema and high schema coverage, the description covers all necessary context: session resumption, workspace fallback, permission behavior, and comparison to codex_continue. It is complete for an AI agent to understand when and how to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no extra parameter details beyond the schema, but it does reinforce that 'sandbox' takes effect here, which is already in the schema. The parameter meaning is well-covered by schema descriptions themselves, so no need for more.

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

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

The description clearly states the tool continues a GitHub Copilot session rooted at a workspace, resuming its session ID. It distinguishes itself from siblings like codex_continue by mentioning permission re-application. The title 'Continue GitHub Copilot session' further clarifies the purpose.

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

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

The description explains when to use this tool: after a copilot_ask, and when you want sandbox permissions to take effect. It contrasts with codex_continue, but does not explicitly list scenarios where alternatives like antigravity_continue are preferred. The fallback behavior after restart is noted, providing context.

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

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

The description goes beyond annotations by disclosing the tool's best-effort nature: the GitHub check 'honors AGY_BRIDGE_NO_UPDATE_CHECK' and auth detection is 'best-effort' with specific caveats. It also notes that the update notice is the same as antigravity_status. No contradictions with annotations (readOnlyHint, idempotentHint).

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

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

The description is concise and well-structured. It opens with a clear summary sentence, then bullet-points the diagnostics items without unnecessary words. Every sentence adds value, and the length is appropriate for the tool's complexity.

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

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

Given the tool has no input parameters and an output schema exists, the description covers all necessary behavioral context: what diagnostics are reported, edge cases (best-effort checks), and the intended debug use case. It is fully complete for the agent to understand and invoke correctly.

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

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

The input schema has zero parameters and 100% coverage, so the description does not need to explain parameters. The baseline of 4 is appropriate as the description adds no additional parameter information.

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

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

The description clearly states the tool's purpose: 'Report diagnostics for the Copilot bridge setup.' It details the specific items checked (version, update, PATH, auth, session state) and explicitly says to use it for debugging 'copilot not found' or auth errors. This distinguishes it from sibling status tools like antigravity_status by focusing on Copilot-specific diagnostics.

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

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

The description provides explicit usage guidance: 'Use this to debug "copilot not found" or auth errors before a call.' It also explains that the update notice matches antigravity_status, implying when to choose this over that. However, it does not explicitly state when not to use it or name alternative tools for other scenarios.

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 indicate mutation and external access, and the description adds context: it uses Cursor CLI, returns stdout, explains sandbox modes (including agent-enforced but not hard boundary), and mentions streaming via watch. This provides valuable behavioral insight beyond the structured annotations.

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

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

The description is two concise sentences in the first paragraph, front-loading the core purpose. Every sentence adds necessary context without redundancy. It is well-structured and efficient.

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

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

Given the complexity (6 parameters, output schema exists), the description covers purpose, authentication, return behavior, and basic use. It lacks explicit error handling or timeout details, but the schema covers most parameters. Overall, it provides sufficient context for an AI agent to use the tool effectively.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by noting that workspace enables context-aware answers and linking to cursor_status for auth, supplementing the schema. It does not repeat schema information unnecessarily.

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

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

The description clearly states 'Ask the Cursor CLI a question or task in a NEW chat', specifying the verb and resource. It distinguishes from sibling 'cursor_continue' by emphasizing 'new chat' and mentions return value and authentication, making the purpose unambiguous.

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

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

The description implies usage for new conversations but does not explicitly state when not to use it or provide alternatives. It references 'cursor_status' for auth but lacks direct comparison with 'cursor_continue'. The guidance is implied but not explicit, warranting a mid-range score.

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

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

The description adds significant behavioral context beyond annotations: it explains the resumption logic (exact chat id from last cursor_ask, fallback to newest chat with matching cwd), how permission flags apply per invocation, and that it works after server restart. No contradictions with annotations (readOnlyHint false, openWorldHint true, idempotentHint false).

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

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

The description is concise with two short paragraphs. The first sentence immediately states the core action. The second paragraph adds necessary detail without fluff. Every sentence adds value.

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

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

Given the complexity (5 parameters, output schema exists), the description covers all essential behavioral aspects: resumption logic, fallback, permission per invocation, and restart resilience. It does not need to explain output schema since it exists separately.

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

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

With 100% schema coverage, the baseline is 3. The description does not add new parameter-level semantics beyond what is already in the schema. It reiterates that sandbox takes effect, but does not provide additional details or context that enhance parameter understanding.

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

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

The description clearly identifies the tool's action: 'continue the Cursor chat.' It uses specific verb ('continue') and resource ('Cursor chat'), and distinguishes from sibling tools like cursor_ask (which starts a new chat) and cursor_status (which shows status).

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

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

The description explicitly states when to use this tool: after a cursor_ask to continue that chat. It also provides context on fallback behavior and permission handling, with an example usage scenario ('analyze read-only with cursor_ask, then continue with workspace-write'), guiding the agent on when and why to invoke this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so no contradiction. The description adds value by detailing the best-effort GitHub update check and the AGY_BRIDGE_NO_UPDATE_CHECK environment variable, providing useful behavioral context beyond annotations.

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

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

The description is composed of four efficient sentences, front-loading the purpose and quota-free nature. Every sentence earns its place, with no redundancy or unnecessary 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?

Given zero parameters, existing output schema, and thorough description of diagnostics reported, the description is fully complete for an agent to understand what the tool does and what it will return.

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

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

With zero parameters, schema coverage is 100% and baseline is 4. No additional parameter description needed.

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

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

The description clearly states 'Report diagnostics for the Cursor bridge setup' with specific resources (bridge version, cursor-agent, login status, chat storage). It distinguishes from sibling antigravity_status by noting the same update notice is shown, clarifying overlap.

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

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

The description explicitly says 'Use this to debug cursor not found or auth errors before spending quota,' providing clear usage context. It lacks explicit when-not-to-use but is sufficient for a diagnostic tool.

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

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

Beyond annotations, the description discloses the experimental status ('has never completed an authenticated round-trip'), warns that it may misbehave and asks to report issues, and states it returns the agent's final message from `--output-format json`. This adds meaningful risk and behavior context not present in structured hints.

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

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

The description is front-loaded with the core purpose and experimental warning in the first paragraph; the second paragraph covers auth, output, and workspace usage. Each sentence is substantive, though slightly verbose.

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

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

Given the tool's complexity, the rich schema/annotations/output schema, and the experimental nature, the description covers the essential risk factors, auth, output, and workspace guidance. It is complete enough for an agent to decide and invoke it safely.

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

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

Schema descriptions cover 100% of parameters with detailed explanations (e.g., sandbox profiles, watch streaming). The description adds no extra parameter meaning beyond a passing mention of workspace location, so baseline 3 applies.

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

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

The description opens with a specific verb+resource: 'Ask Grok Build (`grok -p`) a question or task in a NEW session.' This clearly distinguishes it from grok_continue (explicit 'NEW session') and grok_status.

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 prerequisites ('Needs a SuperGrok / X Premium+ login... or an XAI_API_KEY env var'), directs the agent to 'run `grok_status` first,' and suggests pointing workspace at project dir for context-aware answers. It doesn't explicitly name the alternative for continuing sessions, but the 'NEW session' wording implies the boundary.

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

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

Beyond annotations, the description discloses important behaviors: session pinning via grok_ask's id, fallback to cwd, persistence across server restarts, per-invocation permission flags, and the sandbox's effect. It also notes the experimental caveat and auth requirement, adding value over the structured annotations which only indicate openWorld and read-only state.

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

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

The description is a compact paragraph that front-loads the purpose and then provides necessary technical details. Each sentence contributes useful information — purpose, session mechanism, permission behavior, and experimental caveat — without redundancy or fluff.

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

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

Given the presence of a detailed input schema, annotations, and an output schema, the description is complete enough. It covers the core behavior, session continuity, permission handling, and caveats. It doesn't discuss edge cases like missing prior sessions, but the fallback mechanism partially addresses that, and the experimental tag signals volatility.

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

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

All 5 parameters are fully described in the schema (100% coverage), so the description has little additional semantic burden. It adds one clarifying note that 'sandbox takes effect here too' and ties it to a workflow, but this is marginal relative to the schema's already explicit parameter descriptions.

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

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

The description opens with 'Continue the Grok session rooted at this workspace', which clearly specifies the verb (continue), the resource (Grok session), and the scope (rooted at this workspace). It further explains the mechanics (resuming via session id or fallback to cwd), distinguishing it from sibling tools like grok_ask and grok_status.

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

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

The description provides clear context: it is for continuing an existing session, references the companion grok_ask for read-only analysis, and explicitly recommends using 'workspace-write' to apply fixes. It lacks explicit 'when not to use' or named alternatives beyond grok_ask, but the workflow guidance is strong.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals that no quota is consumed, that auth/model data come from `grok models` which answers even when logged out, and importantly warns that the backend is EXPERIMENTAL with unverified end-to-end behavior. These are valuable behavioral insights.

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

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

The description is front-loaded with the key fact ('spends no quota'), structured into a clear overview, detailed output list, and usage guidance. Every sentence carries unique value and there is no repetition or filler.

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

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

For a zero-parameter diagnostic tool, the description fully covers its purpose, output scope, safety characteristics, usage context, and a crucial caveat about experimental status. The presence of an output schema makes the lack of explicit return-format details acceptable.

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 requires no parameters, so the baseline is 4. The description compensates by explaining what the tool reports, which is more relevant to output than parameter semantics. No parameter information is needed.

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

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

The description states the tool's specific action ('Report diagnostics') and resource ('Grok Build bridge setup'), and immediately clarifies it spends no quota. It distinguishes itself from sibling tools like grok_ask/grok_continue by being a status/diagnostic tool, and even references antigravity_status for the update notice.

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: 'Use this to debug "grok not found" or auth errors before spending quota.' It also positions itself as cheap, safe, and first to call, giving clear decision guidance relative to other tools that spend quota.

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

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

Annotations already flag readOnlyHint=false, openWorldHint=true, idempotentHint=false, but the description adds substantial behavioral context: the tool is experimental and community-verified only, no authenticated round-trip has ever been run, it requires authentication, reads output from stdout, and — critically — 'has NO sandbox and auto-executes every tool call (like antigravity).' This goes well beyond the annotations and fully warns the agent of the tool's dangerous side effects.

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

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

The description is longer than average but every sentence contributes meaningful information: purpose, experimental status, auth steps, return format, what Kimi Code is, workspace tip, and a critical safety warning. It is front-loaded with the primary action and uses line breaks to separate warnings. Slightly verbose but justified by the tool's complexity and risk.

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

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

Given the tool's experimental, unauthenticated, and dangerous nature, the description is remarkably complete. It explains the output (agent's final message from stdout), prerequisites, the safety model (no sandbox, auto-execution), and how to get better results (workspace). The presence of an output schema reduces the need to describe return values, and the description covers the rest comprehensively.

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

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

Schema description coverage is 100%, so all four parameters (model, prompt, timeout_s, workspace) are already documented. The description adds one useful hint for the workspace parameter ('point workspace at a project dir for context-aware answers'), but adds nothing new for prompt, model, or timeout_s. With high schema coverage, this marginal extra keeps it at baseline 3.

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

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

The description opens with a specific verb-resource pairing: 'Ask Kimi Code... a question or task in a NEW session.' This clearly distinguishes the tool from the sibling kimi_continue (which presumably continues a session) and kimi_status. It also names the underlying command (`kimi -p`) and states what it returns, making the tool's function unambiguous.

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

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

The phrase 'in a NEW session' provides clear context for when to use this tool versus continuation alternatives, even though no alternative is explicitly named. It also gives prerequisites (authentication via `kimi login` or API key, then checking `kimi_status`) and a safety restriction ('run it only with trusted prompts on trusted content'). Missing an explicit 'use kimi_continue instead' but otherwise strong.

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

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

Annotations already declare the tool as non-read-only, open-world, and non-idempotent. The description adds meaningful behavioral context: session scoping per working directory (no ID needed), error condition when no prior session exists, and experimental/auth caveats. This goes beyond basic annotations and helps an agent understand prerequisites and side effects.

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

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

The description is three sentences, front-loads the main purpose in the first sentence, and includes only essential details. No extraneous information or redundant restatement of the title.

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

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

Given the tool's moderate complexity (experimental, has prerequisites, multiple parameters) and the presence of an output schema and annotations, the description covers the critical context: how to use it, what will happen if misused, and the experimental nature. It's sufficient for an agent to invoke correctly.

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

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

The input schema covers all three parameters with clear descriptions (100% coverage). The description adds meaning by explaining the session scoping mechanism, which clarifies the 'workspace' parameter's purpose and why no session ID is required. This enriches the schema without radically changing it.

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

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

The description clearly states the tool resumes a prior Kimi session for the workspace via `kimi -c`. It distinguishes from siblings like kimi_ask (starting a new session) and kimi_status (checking status) by specifying the action and workspace scoping. The verb 'continue' is specific and unambiguous.

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

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

The description provides explicit guidance by stating it errors if no prior kimi_ask was run, indicating when the tool is applicable. It also references the same experimental caveat and auth requirement as kimi_ask, framing the appropriate context. However, it doesn't explicitly contrast with alternatives like kimi_ask or kimi_status, so it falls just short of fully explicit.

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

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

Adds substantial context beyond annotations: 'spends no quota,' 'EXPERIMENTAL,' expected auth row prior to login, and backend unverified. These are behavioral traits not captured by readOnlyHint/idempotentHint.

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

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

The description is front-loaded with a clear one-line summary. The subsequent paragraph is detailed but each sentence adds necessary caveats or specifics. Slightly verbose with backticks and examples, but overall efficient.

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

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

With an output schema present and annotations, the description provides complete context: purpose, cost (no quota), experimental status, expected caveats, and specific checks performed. No significant 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?

Tool has zero parameters and schema coverage is 100% trivially. The description doesn't add parameter semantics, but none are needed; baseline 4 applies.

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

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

The description opens with a specific verb and resource: 'Report diagnostics for the Kimi bridge setup'. It enumerates concrete checks (version, newer release, kimi binary, provider, data location) and distinguishes it from sibling status tools by referencing antigravity_status's update notice.

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

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

The description implies use when checking bridge setup, notes 'spends no quota' as a benefit, and warns the backend is unverified. However, it does not explicitly state when to use this instead of kimi_ask/kimi_continue or when not to use it.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, and the description goes well beyond them: it discloses the experimental/unverified status, that failures most likely stem from auth or the model, the auth requirements, and what is returned (the run_terminal event of `muse exec --json`). This is unusually candid context that an agent cannot infer from 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?

Purpose is front-loaded in the first sentence, followed by a clearly delineated warning block and a compact prerequisites/returns block. The multi-line warning is slightly verbose but every line (auth, failure diagnosis, report-it request) carries actionable content.

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

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

Given an output schema exists, return values needn't be spelled out, yet the description even identifies which event carries the answer. Combined with the auth prerequisite and sandbox guidance, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including the sandbox modes and timeouts. The description only re-adds the workspace-for-repo-context cue and the return value, so it mostly repeats the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Ask Meta's Muse Code a question or task in a NEW session') and explicitly scopes it as a new session, which separates it from the sibling muse_continue. An agent can pick between muse_ask and muse_continue without opening either schema.

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

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

Gives a clear prerequisite ('run muse_status first') and the auth condition (Muse plan via `muse login` or META_API_KEY), plus a pointer to --workspace for repo context. It stops short of naming muse_continue as the explicit alternative for resuming, though 'NEW session' strongly implies it.

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

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

Adds meaningful behavior beyond the annotations: session-resolution fallback after server restart, error-rather-than-fresh-start semantics, per-run sandbox application, and auth caveats. It does not contradict readOnlyHint=false or idempotentHint=false, though it defers auth details to muse_ask rather than restating them.

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

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

Purpose is front-loaded and the paragraph is reasonably efficient, with each sentence mostly contributing session-resolution, fallback, or safety context. Minor redundancy appears in the repeated 'experimental' caveat and the cross-reference to muse_ask, but the structure remains readable.

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 session-continuation tool with an output schema and full parameter coverage, the description supplies the critical non-schema context: how sessions are resumed, fallback behavior, and failure mode when no session exists. Return values are covered by the output schema, so no additional return-format explanation is needed.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including watch, prompt, sandbox, timeout_s, and workspace. The description reinforces that sandbox applies per turn but adds little parameter meaning beyond what the schema provides, so 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 ('Continue') and resource ('Muse session rooted at this workspace'), and clearly distinguishes the tool from muse_ask by explaining it resumes an existing session rather than starting fresh. An agent can tell what this 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?

Explains the core usage context—resuming the exact session created by the last muse_ask—and notes the error when no prior session exists, which implicitly routes new-session needs to muse_ask. However, it stops short of an explicit 'use muse_ask when...' statement or broader when-not guidance.

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

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

Annotations already cover readOnly/idempotent/closed-world safety, yet the description still adds substantial behavioral context: what each diagnostic row means, the caveat that a green auth row only proves credentials exist (no live probe), and an EXPERIMENTAL warning that green does not mean a real answer was confirmed. This is exactly the extra context 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?

The quota-free fact and the core purpose are front-loaded, and the enumerated diagnostics are information-dense rather than padding. It runs long across three blocks, but nearly every clause conveys a distinct fact (version, binary, credentials, catalog, sandbox, data location) that an agent would otherwise have to guess.

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

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

For a zero-param diagnostic tool with an output schema, the description is more than sufficient: it names what is checked, caveats the auth signal, and flags experimental status. Nothing an agent needs to decide whether and how to call it is missing.

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

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

The tool takes zero parameters, so per the rubric this earns the baseline 4. The schema is fully empty and there is nothing the description could add about parameter meaning.

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

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

States a specific verb and resource — 'Report diagnostics for the Muse Code bridge setup' — and immediately distinguishes itself from the ask/continue siblings by being a read-only diagnostic. An agent can identify this as the pre-flight check tool 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?

'Spends no quota' gives a clear selection signal: this is the free way to check the bridge before invoking muse_ask. However, it never explicitly says when to prefer it over alternatives or what state it should be run in (e.g. before first use, after a failure).

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 state readOnlyHint=false, openWorldHint=true, and idempotentHint=false, and the description substantially supplements these by explaining auth requirements, the slowness of free queue-scheduled models, timeout_s rationale, and sandbox enforcement being agent-enforced rather than an OS boundary. It also warns against 'danger-full-access' and clarifies that a refused tool call is blocked by opencode, not the kernel.

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

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

The description is longer than average but remains dense and well-organized, front-loading the core purpose before covering credentials, output format, workspace usage, and performance warnings. Every sentence carries operational value; the only reason not to give 5 is that some caveats, such as the slowness warning, are also reflected in the sandbox and timeout parameter descriptions.

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

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

For a tool with open-world capabilities, auth options, sandbox policies, and performance caveats, the description covers the critical ground: no-subscription backend, paid model alternatives, final-message return value, workspace context, timeout behavior, and sandbox limitations. An output schema exists, so detailed return shape doesn't need to be restated. There is no major operational gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful extra meaning beyond the schema: workspace is recommended for context-aware answers, timeout_s defaults to 300 because free models are slow, and model selection guidance encourages a paid model for long tasks. These additions genuinely help an agent choose parameter values.

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: 'Ask opencode (`opencode run`) a question or task in a NEW session.' It clearly distinguishes itself from continuation tools by explicitly stating 'NEW session' and describes what the tool returns (the agent's final message reconstructed from event data).

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

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

The description gives concrete usage context: the free opencode models require zero credentials, a project directory can be pointed to for context-aware answers, and configured paid models are preferred for long tasks. It also mentions 'For a hard boundary, use codex' as an alternative. However, it does not explicitly name or contrast sibling ask tools like codex_ask, copilot_ask, or antigravity_ask.

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

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

The description discloses several non-obvious behaviors beyond the annotations: session id pinning with -s, fallback to -c, per-directory session scoping, and per-invocation permission policy application. Even though annotations already indicate non-read-only and non-idempotent behavior, the description adds critical operational context about restart resilience and scoping. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and is dense with useful information, though it is a fairly long paragraph. Every sentence earns its place, but the final sentence is a long multi-clause construction. It is appropriately sized for the tool's complexity, though slightly more compact structuring would be ideal.

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

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

Given the tool's complexity and the presence of an output schema, the description covers all important behavioral nuances: session continuation, fallback behavior, directory scoping, sandbox semantics, and workflow guidance. Nothing critical for correctly invoking the tool is missing.

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

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

The input schema already covers all 5 parameters with descriptions, so the baseline is 3. The description adds meaningful semantic context: workspace must match the prior session's directory, sandbox applies per invocation with an example value, and watch uses the same viewer as opencode_ask. This raises the score above baseline.

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

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

The description states a specific verb and resource: 'Continue the opencode session rooted at this workspace.' It also explains the exact session-recovery mechanism, which clearly differentiates it from sibling tools like opencode_ask and opencode_status. The purpose is unambiguous and distinct.

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

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

The description gives explicit usage context: it should be used after opencode_ask, the same workspace must be passed, and it works even after a server restart via fallback to opencode's -c behavior. It also provides a practical workflow: analyze read-only with opencode_ask, then continue with workspace-write to apply fixes. This is strong when-to-use guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful context: it specifically reports version info, credential count, model availability, and data location. The note about '0 credentials' not being a failure and referencing antigravity_status's update notice enrich the agent's understanding beyond the structured fields. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and keeps the note about credential interpretation at the end, which is logical. It is concise overall, though the second sentence is a dense run-on list that could be more scannable. Still, every sentence earns its place with no filler.

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

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

Given there are no parameters, an output schema is present, and annotations cover safety, the description is complete. It explains what the tool checks, how to interpret a potentially surprising result (0 credentials), and even links to the related antigravity_status notice. Nothing an agent needs to call or understand this tool is missing.

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

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

The input schema has zero parameters, so the baseline is 4. The description correctly does not attempt to explain parameters since there are none. It instead uses the space to describe behavioral details, which is appropriate.

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

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

The description states a specific verb and resource: 'Report diagnostics for the opencode bridge setup.' It enumerates exactly what is reported (bridge version, opencode presence, credential count, model IDs, data location), which fully clarifies the tool's scope. The resource 'opencode bridge' naturally distinguishes this from sibling status tools for other bridges.

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

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

The description makes clear this is a read-only diagnostic tool by noting it 'spends no quota,' which signals when it is safe to invoke. It also provides interpretive guidance that '0 credentials' is not a failure, helping the agent judge results correctly. It does not explicitly state when to prefer this over siblings, but the tool name and scope make that obvious.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false. The description adds useful behavior beyond that: members run in parallel on the same material, and the panel composition is deterministic across runs. It says nothing about cost, failure/timing behavior, or side effects of an open-world multi-agent run, so it only partially carries the burden for a non-read-only, non-idempotent 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?

Two tight sentences, front-loaded with the action and scope, then the differentiation and the reproducibility benefit. No filler, no restatement of the title.

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

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

An output schema exists, so return values need no explanation, and the schema covers all parameters including defaults. The description adequately conveys what the tool does and why it exists; the only gap is the implicit dependency on a valid preset name, which the description never connects to the swarm_presets sibling.

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

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

Schema description coverage is 100%, so all six parameters (including preset, material, timeout_s, workspace, max_concurrency, watch) are already documented in the schema. The description adds no parameter-level detail such as preset-name syntax or material-size expectations, 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?

Specific verb+resource: 'Run a PREDEFINED swarm' followed by a concrete definition (named panel of agents from different model families, each in its own role, parallel work on the same material). It explicitly contrasts with the sibling agent_swarm ('instead of building agent_swarm tasks by hand'), so the 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?

Clear context: use it when you want a canned panel rather than hand-built agent_swarm tasks, and it notes the reproducibility benefit ('same panel every time') that makes two runs comparable. It does not mention prerequisites such as needing an existing preset name (the swarm_presets sibling is never referenced) or any when-not condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered; the description goes further by disclosing precedence rules (project presets cannot replace built-ins or user presets), the read-only nature of project-sourced members, and that broken files are reported with a skip reason. That is meaningful behavioral context beyond the 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?

The opening sentence is front-loaded with the two modes and the sibling reference before the detail. The parenthetical about read-only repo presets is dense but earns its place by explaining an otherwise surprising restriction; overall there is almost 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 an output schema present, the description need not explain return values, and it still sketches what is listed (kind, members, rubric, source). For a two-param read-only tool the coverage is solid, though it could note the default workspace resolution more explicitly.

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 descriptions already explain both name (show one preset) and workspace (project directory to include). The description restates the name behavior but adds no format or edge-case detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb+resource ('List the predefined swarms') and explicitly covers the dual mode ('or show one in full'), naming the sibling preset_swarm that consumes these presets. An agent can distinguish this inspection tool from preset_swarm's execution role 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?

It gives clear context: listing when name is omitted, full when name is given, and where custom presets live (~/.agent-intern/swarms/ vs <workspace>/.agent-intern/swarms/). It does not explicitly frame when to inspect presets rather than run preset_swarm directly, so an exclusion statement is missing, but the usage context is strong.

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