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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real side-effect context beyond that: it mutates .vscode/settings.json, can launch or attach an IDE window, and injects env vars into every subagent run. It stops short of saying whether launching the IDE window is reversible or what happens on conflicting settings, but that gap is minor given annotation coverage.

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

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

Front-loaded with the verb and resource, then structured into WHEN TO USE, DO NOT USE FOR, and RETURNS blocks. The opening sentence is long but every clause maps to a real capability; nothing is filler, though it 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?

For a 10-parameter, all-optional tool with nested objects and no output schema, the description covers what the tool does, when to call it, what not to call it for, and explicitly inflates the return shape ({ ide_window_attached, opened_ide_window, workspace_environment }). Nothing an agent needs to invoke 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 description coverage is 100%, so the baseline is 3. The description still earns extra credit by explaining the mechanics behind the parameters: auto-detected toolchains, the --add-dir mechanism, and that env/extra_path values propagate to every subagent execution — semantics the schema does not state.

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 (update) and a concrete resource (workspace environment configuration + IDE Visual HUD settings), then enumerates the actual operations: toolchain auto-detection, --add-dir registration, env var injection, .vscode/settings.json sync, and IDE window attach/launch. This is clearly distinguishable from mutation siblings like agy_spawn_swarm or agy_delegate_edit, which operate on agents rather than workspace config.

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 (custom virtualenv/monorepo paths, toggling HUD attachment) and DO NOT USE FOR (read-only status/quota checks, with `agy_status` named as the alternative). The routing condition is unambiguous, so an agent can pick between this and agy_status without inspecting either schema.

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-destructive, non-idempotent. The description adds real value beyond that: the default --mode=accept-edits file-edit-only behavior, the escalation path via allow_shell gated behind AGY_ALLOW_SKIP_PERMISSIONS=1, and what is returned (edit summary, IDE diff confirmation, telemetry footer). It doesn't cover failure behavior or whether edits are revertible, keeping it below 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 labeled blocks (action, WHEN TO USE, DO NOT USE FOR, RETURNS) with the core action front-loaded. Dense but every sentence carries routing or behavioral information; 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?

No output schema exists, and the description compensates by listing return contents. For a mutation tool with five params this is largely sufficient, though it omits error/failure handling and any note on whether accepted edits are recoverable.

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 property descriptions already explain cwd, tier defaults, prompt scope, allow_shell gating, and target_files' HUD/diff purpose. The description adds little parameter-level detail beyond echoing the accept-edits mode. Baseline 3 is appropriate when the schema carries the 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+resource (delegate multi-file code modifications / cross-module refactoring) to a named executor in a named mode. It explicitly contrasts itself with `local_draft_leaf_code`, `agy_delegate_research`, and `local_exec_and_triage`, so an agent can route 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?

Has an explicit WHEN TO USE condition (coordinated edits across multiple existing files needing Gemini Argon/Flash reasoning) and a DO NOT USE FOR block naming three alternatives with their own scoping conditions. Exclusions and alternatives are both 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety burden is largely covered. The description supplements this with the return shape (Markdown with <file>:<line> citations and a telemetry footer) and a quota signal ('0x quota' for the local alternative, implying agy calls consume quota). It stops short of stating cost/latency expectations per tier or any auth prerequisites.

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

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

Dense but fully front-loaded: purpose first, then WHEN TO USE, DO NOT USE FOR, and RETURNS as labeled clauses. Every clause carries routing or behavioral information; nothing is filler.

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

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

No output schema exists, and the description compensates by describing the return format (Markdown analysis with file:line citations plus telemetry footer). Combined with explicit routing guidance and full schema coverage, an agent has what it needs to call it correctly; only cost/quota-consumption per tier and expected latency are left unstated.

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 in-schema, and the description adds essentially nothing about individual parameters beyond corroborating flash/argon model naming for the `tier` enum. Baseline 3 applies when the schema carries the parameter burden.

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

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

Names a specific verb (delegate) and a concrete resource (deep read-only codebase research, architectural analysis, root-cause tracing, security verification) plus the target executor (Google Antigravity CLI in --mode=plan). The scope ('complex multi-file reasoning... 5–30+ files') distinguishes it cleanly from the shallow-scouting and swarm 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?

Explicit WHEN TO USE ('complex multi-file reasoning or architectural audits across 5–30+ files after initial scouting') and explicit DO NOT USE FOR with named alternatives: `local_file_scout` for signature/import/line-number extraction and `agy_spawn_swarm` for parallel disjoint directory scans. Both exclusions name a concrete sibling from the available set.

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, idempotentHint=false and destructiveHint=false, so the mutation profile is covered. The description adds genuine behavioral context beyond that: files stay in the context cache and the session auto-compacts above 80% usage, which the agent could not infer from structured fields. It stops short of describing permission/auth requirements or what a compaction notice implies operationally.

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

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

Three front-loaded blocks — purpose, WHEN/DO NOT USE, RETURNS — with no filler sentences. The cache and compaction details are folded into the opening sentence rather than padding a separate section.

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?

Although no output schema exists, the RETURNS section enumerates the follow-up response, optional compaction notice, and updated telemetry. Combined with the WHEN/NOT routing and cache behavior, an agent has everything needed to select and invoke 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% and every parameter is already documented, including the enum values for mode and tier. The description only echoes the conversation_id syntax ('--conversation <id>') and adds nothing about mode, tier, or cwd semantics, so it sits at the baseline where the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource ('Resume an existing Antigravity conversation ID') and immediately adds the mechanism (--conversation <id>) plus the cache-preservation rationale, so the agent knows exactly what the tool does that a fresh call would not.

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

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

It provides an explicit WHEN TO USE clause bound to a prior `agy_delegate_research`/`agy_delegate_edit` session ID, and an explicit DO NOT USE FOR clause routing brand-new tasks to `agy_delegate_research`. Both the trigger condition and the named alternative are stated, 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is carried. The description still adds value beyond that: the disjoint-partition validator will reject overlaps, subagents are read-only, the model tiers used, and the return shape (aggregated markdown plus telemetry footer) which matters because there is no output schema. It does not quantify limits such as max task count or failure handling.

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?

A single dense paragraph with front-loaded purpose followed by labelled WHEN TO USE, DO NOT USE FOR, and RETURNS clauses. Every sentence carries an actionable constraint; no filler.

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

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

For a tool with no output schema and 100% schema coverage, the description covers purpose, exclusions, partitioning constraint, and return shape. The one ambiguity left is when to prefer the flash-medium tier over the default flash-low, which the description names but does not differentiate.

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 both the cwd and the nested task fields (id, tier, paths, prompt) are already documented with examples and constraints. The description only restates the disjoint-path rule and the tier names; it adds no format or syntax 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 (dispatch read-only subagents) plus the defining constraint: strictly disjoint directory partitions and specified model tiers. This is immediately distinguishable from agy_delegate_research and local_file_scout, which the description names as alternatives.

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

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

Explicit WHEN TO USE (multiple independent subsystems/directories in one turn) and DO NOT USE FOR with the exact sibling to use instead for each excluded case, including that overlapping paths are rejected by the validator. 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 readOnlyHint=true and idempotentHint=true, so the 'read-only mode' statement is partly redundant. However, the description adds genuine context annotations do not carry: the specific probe endpoint (`/api/ps`), that the response includes a telemetry footer, and the shape of the report. It stops short of noting that `refresh_models` makes the call slow, which is the main behavioral gotcha.

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 resource list, then uses labeled WHEN TO USE / DO NOT USE FOR / RETURNS blocks, so structure is easy to scan. The capability sentence is long and dense with parenthetical detail, but every clause maps to a distinct probed subsystem rather than 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?

No output schema exists, and the description compensates by enumerating the returned JSON keys (`agy_process_queue`, `local_gpu_queue`, `local_gpu_probe`, `local_gpu_telemetry`, `model_quotas`, `sessions`). Combined with the exclusions, an agent has everything needed to decide to call it and interpret the result.

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

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

Schema coverage is 100% and the single parameter `refresh_models` is documented in the schema with its default and the `agy models` probe side effect. The description adds no parameter guidance beyond what the schema provides, so baseline 3 applies.

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

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

Uses a specific verb ('Inspect') plus an enumerated set of concrete resources: system health, Gemini quota windows, Local GPU VRAM via `/api/ps`, process queue, session context, and Git worktree pre-flight. An agent can distinguish this diagnostic tool from siblings like `agy_configure_workspace` or `local_exec_and_triage` 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?

Contains explicit WHEN TO USE ('checking whether the Local GPU worker or Gemini Argon/Flash tiers are online and inspecting token savings') and DO NOT USE FOR ('Modifying workspace settings or attaching the IDE') with a named alternative (`agy_configure_workspace`). Both the positive trigger and the exclusion route the agent unambiguously.

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 validation gates (>=15 chars, closed markdown fences, no truncation placeholders), the automatic abort of the disk write, the offline fallback to agy_delegate_edit, and the server-side reading of reference_files. annotations only supply generic hints (readOnly=false, destructive=false, not idempotent), so this added detail is exactly the value the description should provide.

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

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

Front-loaded with the action sentence, then clearly delineated WHEN TO USE / DO NOT USE FOR / RETURNS blocks. Dense but every clause carries operational information; nothing is redundant with the schema or annotations.

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

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

For a single-file write tool with 4 params and no output schema, the description covers the return payload (write confirmation, byte/line counts, git diff --stat), failure handling, and escalation. Nothing an agent needs to call it safely 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, but the description adds real meaning: it clarifies that reference_files are read server-side as style/type/import references and that target_file is written automatically only after validation passes. It doesn't clarify cwd semantics or overwrite behavior for an existing target_file, which keeps it from a 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 ('Draft') plus concrete artifact types (leaf-node boilerplate, unit tests, DTOs, schemas) and the execution backend (Local GPU LLM). It explicitly names the sibling it is not (agy_delegate_edit for multi-file work), so an agent can separate it from its siblings 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?

Contains explicit WHEN TO USE ('single self-contained leaf file') and DO NOT USE FOR ('complex multi-file refactoring or cross-module architectural edits') with the correct alternative named. The escalation path to agy_delegate_edit flash-high on failure is also 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?

Goes well past the annotations by disclosing process-tree kill protection via `taskkill /T /F`, the 40-line output threshold, and what the scrubbed digest actually contains (exit code, failing test names, file:line, isolated stack traces). It does not contradict readOnlyHint/destructiveHint=false, since running tests and linters is a non-mutating read of the codebase. Minor gap: no note on whether the subprocess inherits env or has network access, which matters given openWorldHint=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?

Front-loaded with the action and the concrete command set, then cleanly segmented into WHEN TO USE, DO NOT USE FOR, and RETURNS. Dense but every clause carries operational information; 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 RETURNS section is essential and present, explaining both the pass-through case and the digest format. Combined with the safety mechanism and the exclusion list, an agent has everything needed to call this correctly against a 3-parameter, non-idempotent execution 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 command, timeout_ms, and working_dir are already documented in structured fields. The description reinforces the allow-list and no-chaining rule for `command`, but adds no syntax or format detail the schema lacks, and says nothing about timeout semantics beyond the schema's default/max. 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 (execute) plus the exact resource class (allow-listed test/build/typecheck/lint commands) and enumerates concrete examples (pytest, npm test, npx tsc, cargo check, go test). Nothing overlaps with siblings like local_file_scout or local_draft_leaf_code, so an agent can route on the first clause alone.

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?

Has an explicit WHEN TO USE clause (>40 lines of noisy output from tests/compilers/linters) and an explicit DO NOT USE FOR clause (chained shell operators, file edits). Both the selection condition and the exclusion 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description still adds real behavior: zero cloud quota consumption, a hard <300 token output cap, a NOT_FOUND_ON_DISK sentinel for missing symbols, and automatic escalation to a cloud model when the local GPU is offline. The remaining gap is the vague 'telemetry footer' it promises without explaining.

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?

Structured as WHEN TO USE / DO NOT USE FOR / RETURNS with the core identifier front-loaded, and nearly every clause carries operational information. It loses a point for shouting caps and branding ('ZERO-TRUST MEMORY TOOL', '0x cloud quota') that adds emphasis rather than new meaning.

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

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

There is no output schema, so the RETURNS section properly compensates with the digest format, citation style, and the failure sentinel. Minor omissions remain: behavior with multiple file_paths, and what happens when a path itself does not exist versus when a symbol is absent.

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

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

Schema description coverage is 100%, so the schema already documents cwd, query, and file_paths fully — baseline 3 applies. The description only marginally extends this, tying 'query' to the NOT_FOUND_ON_DISK sentinel and reiterating the file-type exclusions that the schema already states.

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

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

States a concrete verb and resource ('Read repository files directly from disk') plus the processing model (local GPU LLM as forensic extractor) and the exact output shape ('verbatim signatures, imports, and logic with exact 1-based <file>:L<line> citations'). It also names its boundary against the sibling 'agy_delegate_research', so an agent can distinguish it 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?

Explicit WHEN TO USE ('always call before raw Read on unfamiliar/large files (>150 lines) or whenever verifying disk state') and explicit DO NOT USE FOR ('multi-directory architectural synthesis across 10+ files (use agy_delegate_research after scouting)'). Both the positive trigger and the hand-off alternative are named, 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.