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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description usefully narrows the blast radius ('one ... job', not the server), but says nothing about what happens to in-flight work or partial results, so it adds modest context on top of the annotations.

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

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

A single front-loaded sentence with no padding, which is structurally good, but 'Boundedly' and 'typed' are undefined terms that cost the reader more than they convey.

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

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

For a one-parameter, no-output-schema mutation whose annotations carry the safety semantics, the essentials are nearly there: it says what is cancelled and that the server survives. It still omits how a job_id is obtained and what a successful cancel returns.

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

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

Schema description coverage is 0% for the single required job_id, and the description supplies nothing about it — no format, no source (presumably from grok_agent_start or grok_agent_poll), no validity/lifetime conditions. With one undocumented parameter the description should compensate and does not.

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

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

States a specific verb and resource ('cancel one ... job') and scopes it against a sibling-adjacent action by saying it does not stop the MCP server. The qualifiers 'boundedly' and 'typed' are undefined jargon, so the action is clear but the modifiers add noise rather than precision.

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 only usage signal is the implicit contrast 'without stopping the MCP server', which hints at a when-not condition but names no alternative tool (e.g., grok_agent_session_end or grok_delegate_* teardown paths) and gives no prerequisites such as needing a live job_id.

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 read-only/open-world/idempotent, and the description adds non-obvious behavior on top: a 24 h cache and what fields come back ('current, latest, notes link, update command'). It does not say what happens on GitHub failure or rate limits, but the added caching detail goes meaningfully beyond the annotations.

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

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

Four short clauses, all front-loaded: what it does, when to use it, behavioral caveat, return shape. No filler and nothing buried.

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

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

With no output schema, the description carries the return-shape burden and does so by enumerating the four returned fields, plus the caching caveat. Nearly complete, though failure modes and the check-then-update workflow with grok_agent_update are left implicit.

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

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

Schema coverage is 100% with a single documented param, so baseline is 3. The description's 'cached 24 h' explains the raison d'être of the force flag (bypass the cache), adding context beyond the schema text rather than merely restating it.

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

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

States a concrete verb and resource: 'Compare the installed bridge with the latest GitHub release.' The read-only framing implicitly separates it from the mutating sibling grok_agent_update, though that sibling is never named, so an agent must infer the check-vs-apply split.

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?

'Use when the user asks about updates or instructions show an update line' gives an explicit trigger condition. It stops short of saying when to prefer this over grok_agent_update (i.e. check first, then apply), so the routing is implied rather than stated.

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

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

The title ("Consult (read-only)") and description ("read-only consult session") assert a non-mutating operation, while annotations declare readOnlyHint=false, and the schema even accepts permission_profile="workspace". An agent cannot tell from the definition whether the call is truly read-only, so the surfaced signals conflict rather than complement.

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

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

One short sentence with the purpose front-loaded, so it is not verbose. However, the second clause is unexplained jargon that consumes space without conveying actionable meaning to an agent.

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

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

This is a session-launching tool with a large nested task packet and no output schema, yet the description omits how results are later retrieved (grok_agent_status/poll), timeouts, and the meaning of lane/transport. One sentence is far too thin for the tool's actual complexity.

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

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

Schema description coverage is 0% across three parameters (lane, task, transport), including a nested task packet with ~20 fields, and the description says nothing about lane, transport, or any packet field. The only fragment of parameter meaning is the cryptic "non-git exact allowlisted roots" line, which at best gestures at project_root/mount_paths.

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 ("Start an isolated read-only consult session"), so an agent can tell this spawns a consultation rather than executing or fixing code. It does not name or contrast any sibling (grok_agent_review, grok_delegate, grok_agent_execute), so differentiation relies on inference.

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

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

There is no when-to-use guidance, no prerequisites, and no alternative named. The clause about "non-git exact allowlisted roots" reads like a constraint but is never tied to a decision an agent would make, so usage is only implied by the tool name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds 'no secrets' (largely redundant with the read-only annotation) and a 'call once' usage trait, but says nothing about content size, caching, or what the playbook actually contains beyond topic labels.

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

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

Two tightly packed sentences with the purpose front-loaded and the key usage rule ('call once') placed immediately after. Zero filler words.

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

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

For a zero-parameter, read-only advisory tool with no output schema, the description covers what it is and how to invoke it. It is slightly thin on scope (how long the playbook is, whether it supersedes other tools' docs), but nothing essential for correct invocation is missing.

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

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

The tool takes zero parameters, so there is no parameter surface for the description to explain; baseline is 4. No misleading parameter claims are present.

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 it is a 'token-economy playbook' that covers when to consult vs execute, polling receipts, and VPS offload tips, which distinguishes it from the action-oriented siblings like grok_agent_execute and grok_agent_poll. It is clear it delivers guidance rather than performing an operation, though it never explicitly says it returns a document/guide.

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?

'Call once; prefer over re-planning' gives concrete invocation guidance and implies when-not (don't call repeatedly). It references the consult-vs-execute decision, pointing at siblings conceptually, but does not name them explicitly as alternatives.

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

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

Annotations already declare destructiveHint=false, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety and side-effect profile is covered. The description adds two genuinely useful facts beyond that: execution happens in an isolated git worktree, and completion requires a real diff plus the requested evidence. It omits auth/permission needs (the task's permission_profile enum hints at this), concurrency behavior, and that each call spawns a fresh non-idempotent run.

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

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

Two short sentences, front-loaded with the core action. Nothing is padded, though the second sentence is telegraphic and its referent ('completed', 'requested evidence') is unclear without prior knowledge of the task packet.

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

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

This is a high-complexity tool: a nested required task packet with 20 fields, no output schema, and no schema-level descriptions anywhere. A two-sentence description leaves an agent guessing about required packet contents, lane/transport semantics, and what a successful invocation returns.

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

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

Schema description coverage is 0% across three parameters, and the nested task object carries ~20 undocumented fields (objective, expected_artifacts, test_commands, acceptance_criteria, permission_profile, etc.). The description explains none of them, so it fails to compensate for the coverage gap; the only faint signal is 'requested evidence', which loosely gestures at expected_artifacts.

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: 'Start workspace execution in a git worktree'. An agent can tell this launches a run rather than merely polling or reviewing. However, it does nothing to distinguish itself from the many sibling start/execute tools (grok_agent_start, grok_delegate_start, grok_agent_consult), so the sibling-differentiation criterion for a 5 is unmet.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative among the ~24 siblings. The trailing clause about 'completed' describes an outcome condition, not when an agent should pick this tool over grok_agent_start or grok_delegate_start.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is partially covered. The description adds the useful 'separate workspace' isolation and bounded mutation scope, but omits that this launches an asynchronous, non-idempotent session requiring subsequent poll/status calls to observe progress.

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 front-loaded sentence with no filler, efficiently stating the action and scope. It is arguably over-terse for the complexity of the nested packet, but nothing is wasted.

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

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

For a tool whose only real payload is a large nested object, with 0% schema coverage and no output schema, the description omits the session lifecycle (start, then poll/status/cancel), permission profile, and packet construction guidance. The agent cannot construct a valid call from this description alone.

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

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

Schema description coverage is 0% and the description says nothing about lane, task, or transport. A ~25-field nested task packet is passed as the required argument, yet the description never mentions the packet structure, the required fields, or that role should be set to 'fix' for this tool. This is a substantial gap the description fails to compensate for.

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: start a fixer session scoped to confirmed findings in a task packet. That distinguishes it reasonably from grok_agent_execute and grok_agent_review by naming the fix role and its input scope, but it never names those siblings explicitly and leaves the domain (code fixing in a worktree) implicit via the title only.

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?

'Scoped to confirmed findings in the task packet' hints that this is called after a review has confirmed findings, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many session/execute/review siblings. The agent must infer the pipeline position.

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 openWorldHint=false, so safety is covered. The description adds that reads are 'bounded' and that a terminal 'evidence receipt' is available, but says nothing about rate limits, polling cadence, or what happens when the job is still running beyond the start of the wait.

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 front-loaded sentence with no filler; 'bounded' and 'final evidence receipt' both carry weight. Slightly terse for a 3-parameter tool but structurally sound.

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

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

With no output schema, the description carries the burden of explaining returns; it gestures at 'progress/events' and a 'final evidence receipt' but gives no shape, fields, or terminal-state semantics. Combined with undocumented job_id/limit and no routing guidance among three status/poll siblings, it is only minimally complete.

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

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

Schema description coverage is only 33%: wait_seconds is documented in the schema (including blocking and notification behavior) while limit and job_id have no description anywhere. The tool description adds nothing about what limit bounds or the format/expected value of job_id, so it fails to compensate for the coverage gap.

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

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

States a specific verb (read) and resource (bounded progress/events and the final evidence receipt) scoped to a typed job, which is more informative than the title 'Poll agent job'. However, it never distinguishes itself from the sibling grok_agent_status or grok_delegate_status, leaving an agent unsure which polling verb to choose.

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

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

No when-to-use guidance is given. It does not say when to poll versus calling grok_agent_status, nor whether polling should precede or follow grok_agent_execute, and the only usage note ('as before') refers to prior behavior rather than routing logic.

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

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

Annotations mark it non-readOnly, idempotent, non-destructive, closed-world. The description adds valuable detail beyond that: it writes a file (.grok-mcp.json) only when a preset is supplied, otherwise it's a read. This dual mode is not derivable from the idempotent/non-destructive hints. Minor gap: doesn't say which permissions or whether it errors on missing file.

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

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

Three tight sentences, front-loaded with the operation and value domain. No wasted words, but the telegraphic style ('it reports/writes') is slightly terse for an agent needing precision.

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, 3 params with 0% schema coverage, so the description carries responsibility. It covers the core read/write semantics and trigger condition but omits what 'reports' returns and what 'project_root'/'note' do, leaving gaps an agent might need. Just adequate.

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

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

Schema description coverage is 0%, so the description must compensate, but it only names the enum values (off/cheap/standard/max) implicitly via 'preset' and never explains 'project_root' or 'note'. Baseline of 3 is appropriate since the enum is the key semantic and the description implies its role, but the two undocumented non-enum params remain unexplained.

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

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

States a specific dual-purpose operation (read or set the project's Grok preset) named after the config file it manages. The name 'grok_agent_project' is generic, but the description clarifies the resource is the '.grok-mcp.json' preset. Distinguishable from siblings like grok_agent_status/economy, though not explicitly compared.

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 triggering condition: 'Use first when a job tool returns PROJECT_NOT_ENABLED,' which is strong actionable guidance. Also clarifies the read-vs-write behavior: 'Without preset it reports; with preset it writes.' No explicit exclusions of alternatives named, but the context is clear.

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

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

Annotations already declare openWorldHint=true, idempotentHint=false, destructiveHint=false, so the agent knows this spins up external, non-repeatable, non-destructive work. The description adds only 'independent' and 'session' on top of that, and says nothing about whether the call blocks or returns a handle, how sessions are retrieved/ended (grok_agent_status/poll/end), timeouts, or model/permission behavior. The phrase 'read-only' is also in tension with readOnlyHint=false, though the main verb 'Start' describes a state-changing operation and 'read-only' plausibly characterizes the skeptic session's permission profile rather than the tool itself.

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 front-loaded sentence with no filler or repetition; the core purpose is stated in the first few words. It is efficient, though for a tool of this complexity the brevity shades into under-specification rather than crispness.

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

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

This is a complex tool: a large nested task packet, enums for role/permission_profile/reasoning_effort, and no output schema to lean on. One vague sentence does not cover the required fields, the transport option, or what the caller receives back, leaving an agent without enough to invoke it confidently beyond the annotations' safety profile.

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

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

Schema description coverage is 0% on a nested 'task' object with roughly eighteen undocumented properties (objective, project_root, correlation_id, lane, transport, permission_profile, etc.). The description only vaguely gestures at 'evidence/diff inputs', which at best hints at task.inputs/base_ref, and does not compensate for the near-total absence of parameter documentation.

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 ('Start') and a concrete resource ('independent ... skeptic session over supplied evidence/diff inputs'), and the word 'skeptic' maps to the role enum, implicitly separating it from the execute/fix/consult siblings. It never names a sibling explicitly, so it is clear but not fully differentiating.

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

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

There is no when-to-use guidance, no when-not-to-use, and no named alternative among the many grok_agent_* / grok_delegate_* siblings. Nothing states the prerequisites (a task packet containing objective, project_root and correlation_id) or when a user should pick this over grok_agent_execute or grok_agent_fix.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description goes further by listing what the call returns (mode, plan, budget, deny_tools, host_script, skill_ref) — genuinely additive since there is no output schema — and names the internal machinery (plan compiler + budget guard). It still does not say what state the session creates or how long it persists.

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

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

Dense and front-loaded: the action and its two subsystems come first, inputs next, outputs third, and the ordering imperative last. It is telegraphic rather than wasteful, though the 'Session Protocol v1.2' version tag carries little decision value for an agent.

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 no-required-parameter bootstrap tool in a large sibling cluster with no output schema, the description does supply return fields and call ordering. But five of eight inputs remain unexplained and there is no guidance on defaults or on the session lifecycle it initiates, leaving the definition minimally adequate rather than complete.

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

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

Schema description coverage is only 13% across 8 parameters, so the description must compensate, and it largely does not: 'goal (≤500)' and 'host_budget tiny|small|normal' merely restate constraints already in the schema, while project_root, test_commands, correlation_id, max_tool_calls, and expected_artifacts are undocumented in both places. It does not explain the semantics of the intent enum or how max_tool_calls interacts with the budget guard.

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: 'begin session with plan compiler + budget guard', and 'Call first' positions it as the entry point in the session lifecycle alongside tick/next/end siblings. It does not distinguish itself from other starters like grok_agent_start or grok_delegate_start, so it is clear but not fully sibling-differentiated.

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

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

'Call first' gives explicit ordering guidance, which is the key usage signal for a session bootstrap tool. However, there is no statement of when not to use it, no prerequisites, and no routing to alternatives such as grok_agent_start or grok_delegate_start.

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

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

Annotations already flag this as a non-read-only, non-destructive, closed-world mutation, so the safety profile is partly covered. The description adds genuine behavioral detail beyond that: the receipt shape and the 'no auto-create' guarantee for suggest_issue (a scrubbed draft is returned, nothing is written). It still omits what ending the session actually does to 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?

It is compact and front-loaded, but the 'Session Protocol v1.2:' prefix is low-value jargon and the two clauses are dense shorthand rather than clearly parsed guidance. Brevity here reads more as under-specification than efficient structure.

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

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

For a 4-parameter mutation with no output schema and 0% schema coverage, the description is too thin: it omits parameter meanings, prerequisites, and what state change ending the session causes. The receipt description helps slightly but leaves major gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the param burden. It only partly covers one parameter (suggest_issue returns a scrubbed draft, no auto-create), while note, job_id, and session_id are entirely unexplained in both schema and description.

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

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

The description names an output artifact ('short receipt' with status/job/changed/tests/next) and the optional suggest_issue behavior, but never states the actual action of ending a session in prose. An agent gets the verb only from the name/title, not from the description, and the 'Session Protocol v1.2' framing is opaque jargon rather than a purpose statement.

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

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

There is no when-to-use guidance and no reference to the sibling lifecycle tools (grok_agent_session_begin, grok_agent_session_tick, grok_agent_session_next). An agent cannot tell from the text when ending is appropriate versus continuing with session_tick or session_next.

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, destructiveHint=false, openWorldHint=false, and the description is consistent with that (it advances protocol state), adding the done=true termination signal and a protocol version marker. It still does not disclose what state changes on each call, why it is not read-only, or whether repeated calls are idempotent.

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 front-loaded sentence with no filler; the type enumeration is compact and readable. The compression is slightly aggressive for a protocol tool, but nothing is wasted.

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

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

For a stateful protocol navigator with no output schema and 0% parameter documentation, the description should explain the session lifecycle, the card's fields, and the three inputs. It gestures at the loop but leaves an agent unable to call the tool correctly without external 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 0% for three parameters (note, advance, session_id), and the description mentions none of them. With no structured or textual explanation, an agent has no way to know what 'note' feeds into or what advance=false does versus the default true.

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

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

The description names the return artifact ('ONE next action card') and its possible shapes (host_cmd|mcp_tool|end), which is more specific than the title alone, but the operative verb is buried in jargon ('Session Protocol v1.2 navigator'). It does not differentiate itself from close siblings such as grok_agent_session_tick, session_begin, or session_end, leaving the agent to infer the boundary.

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?

'Host loops this until done=true' is real usage guidance: it tells the caller this is a polling-style call with a termination signal. However, it never says when to prefer this over session_tick or session_begin, nor what preconditions (e.g. an open session_id) must hold.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context by naming the return fields (step, steps_left, budget_remaining, force_end) and the budget-counting trigger, but it does not explain what force_end implies or how state is mutated.

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 tight, front-loaded cluster of sentences with no filler: protocol banner, return contract, usage hint, and default note. It is efficient, though the extreme terseness borders on cryptic.

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 stateful session/budget tool with 5 undocumented parameters and no output schema, the description is too thin. It lists return field names but not their meaning, omits job_id vs session_id, and never explains how ticks relate to the surrounding session lifecycle tools.

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

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

Schema description coverage is 0% across 5 parameters, so the description must carry the burden. It covers only three of them (tool_used/step_done semantics, verbose default false) and leaves the two identifier parameters, job_id and session_id, completely unexplained.

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

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

The description frames the tool as 'Session Protocol v1.2: compact progress + budget' and lists return fields, so an agent can infer it reports session step/budget state. However, the verb 'tick' is jargon and the description never differentiates this from siblings like grok_agent_session_next or grok_agent_session_begin, leaving the exact purpose somewhat vague.

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?

'Pass tool_used/step_done to count budget' implies usage occurs after completing a step, which is a partial usage cue. But there is no explicit when-to-use vs session_begin/session_next/session_end, and no prerequisites or exclusion conditions are stated.

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

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

With annotations already declaring non-read-only, open-world, non-idempotent behavior, the description adds the genuinely useful async execution nature and transport semantics. It does not disclose required permissions, whether a job handle/ID is returned, what happens on task-schema violation, or any timeout/cancellation implications.

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

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

Two sentences, purpose front-loaded, no filler. The second sentence is a useful caveat about the transport default rather than padding, though the dense jargon slightly works against fast comprehension.

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

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

A mutation tool with a deeply nested, fully undocumented task payload, no output schema, and 0% parameter coverage needs far more from the description. It omits the shape of the task packet, the meaning of lane/role, the return value, and the follow-up lifecycle, leaving an agent unable to construct a valid call from the description alone.

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

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

Schema description coverage is 0% across three parameters, including a large nested 'task' object with 15+ undocumented fields (role, lane, permission_profile, acceptance_criteria, etc.). The description only clarifies one enum value by noting 'auto means stdio only'; 'lane' and the entire task packet contract are left unexplained.

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

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

States a specific verb and resource ('start a versioned typed task packet'), which distinguishes it from the status/cancel/review siblings. However, 'task packet' is opaque jargon an agent may not decode, and it never distinguishes itself from close siblings like grok_agent_execute or grok_delegate_start.

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

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

No when-to-use or when-not-to-use guidance. There is no mention of how this differs from grok_agent_execute, grok_agent_fix, or grok_delegate_start, nor any prerequisite or lifecycle context (e.g., that a started job is later polled via grok_agent_status). The only usage hint is a transport default note.

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 openWorldHint=true, and the description merely repeats 'Read-only' rather than adding to it. It does add value by enumerating the subsystems covered (daemon and durable job status, transport router), but says nothing about auth requirements, output shape, or rate limits.

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 short sentence with no filler, though it is dense with internal jargon ('transport router', 'exact roots') and the 'Read-only' clause is redundant with the 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 zero-param diagnostic tool with no output schema, the description should convey the shape of what comes back; it lists the reported components but not their format, so it is adequate but incomplete.

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 the baseline of 4 applies; there is nothing for the description to disambiguate.

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 enumerates what status is reported (version/auth-presence, roots, transport router, daemon, durable job status), so the agent can infer this is a diagnostic dump tool. However there is no verb and no differentiation from the very similar sibling grok_delegate_status, leaving the exact scope ambiguous.

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

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

No when-to-use guidance, no prerequisites, and no alternative named despite an obvious overlapping sibling (grok_delegate_status) plus grok_agent_poll. The agent must guess when this is preferred.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds the concrete side effects an agent needs: preview-only behavior without confirm, then pull, reinstall, and a host restart. The 'refuses a dirty checkout' precondition is a real operational constraint not captured by any annotation.

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

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

Four short sentences, purpose front-loaded, then prerequisite, then mode semantics, then failure condition. No filler and nothing restated from the title or schema.

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

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

For a one-parameter mutation with no output schema, the description covers mode behavior, precondition, and the restart side effect. It stops short of telling the agent how to recover from the dirty-checkout refusal or whether a host restart can be deferred, which is the only remaining gap for a destructive operation.

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

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

Schema coverage is 100% and the schema already says 'Run the update. Omit to preview it.', so the description adds limited syntax detail. It does go beyond the schema by specifying what happens in preview mode ('only reports steps') and in execute mode (pull, reinstall, restart host), which is meaningful semantics for the single flag.

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 gives a specific verb and resource ('update the bridge checkout from its git remote'), which is unambiguous among siblings like grok_agent_status or grok_agent_execute. It also names the sibling it pairs with (grok_agent_check_update), so the agent can place it precisely in the workflow.

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 the trigger condition explicitly: use after grok_agent_check_update reports a newer version. It also gives a precondition ('refuses a dirty checkout') that tells the agent when the call will fail, but there is no stated exclusion against just re-running it or any mention of alternative update paths.

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 a non-read-only, open-world, non-idempotent, non-destructive write. The description usefully adds the safety envelope (isolated worktree, no push, no merge, no --always-approve) and the sync return (branch + diffstat), which is real context beyond the annotations. It stops short of noting auth/permission prerequisites or failure modes.

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

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

Three tight sentences, front-loaded with the action and scope, then the return value, then the negative constraints. Every clause 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?

For a 20-parameter mutation tool with no output schema, the description adequately conveys the operation, its boundaries, and its return shape, while annotations carry the safety profile. It is complete enough to call correctly, though the routing relationship to the other grok_delegate_* tools is left implicit.

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

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

Schema description coverage is 100%, so the schema already documents all 20 parameters in detail. The description adds no parameter-level meaning (e.g., it does not explain the lane_verdict vs plan_only interaction or the allowlist constraints), so it neither helps nor hurts beyond the baseline.

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

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

States a specific verb (delegate) and resource (coding goal to local headless grok in an isolated git worktree on a grok/* branch), plus the sync return (branch + diffstat). It clearly says what it is not (the product admin-bridge, dev-only), but it never distinguishes itself from the very similar sibling grok_delegate_start/plan, which the agent must infer from the '(sync)' title.

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?

Offers some when-not guidance: 'Dev-only — not the product admin-bridge' and 'No push, no merge, no --always-approve' bound the intended context. However it gives no explicit rule for choosing this tool over grok_delegate_start, grok_delegate_plan, or grok_agent_execute, leaving the primary routing decision 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 openWorldHint=true, covering the safety profile. The description adds only that it runs read-only (`--json`, never fix) and returns JSON, which largely restates the annotation. It does not disclose side effects, timing, or environment requirements beyond the fix exclusion.

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 terse sentences, front-loaded with the exact command and the key constraint. Every phrase earns its place with no padding.

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 parameterless diagnostic tool with no output schema, the description conveys enough to invoke correctly: what command runs, that it is read-only, and that it returns JSON. Return-value structure is not elaborated but is implied by '--json'.

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 the baseline is 4. There is nothing for the description to clarify regarding inputs.

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

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

States a specific verb+resource: run `grok doctor --json` for diagnostics. The 'doctor' framing and 'diagnostic JSON' clearly convey the tool's purpose. However, it does not differentiate itself from the many sibling grok_* tools beyond the diagnostic framing.

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 parenthetical '(never doctor fix)' gives an explicit exclusion, steering the agent away from a mutating variant. It stops short of naming sibling tools or broader when-to-use conditions, but the command-level constraint is clear 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 annotations already declare readOnlyHint=true and openWorldHint=true, and the description's 'Read-only' largely restates that. It does add one constraint beyond the annotations – that the root must be allowlisted – but discloses nothing about what the inspection covers, its cost, or its failure modes.

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 brief sentences, front-loaded with the action, with no filler. Every clause carries signal.

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

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

For a single-parameter read-only tool with an output schema absent but annotations covering the safety profile, the definition is minimally adequate. It tells the agent it emits JSON and requires an allowlisted root, but never explains what an 'inspect' actually reports, which is the main 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 description coverage is 100%, so the single repo_root parameter is already documented as 'Allowlisted project root to inspect'. The description adds no syntax, format, or constraint detail beyond the schema, so baseline 3 applies.

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

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

Names a specific action and resource ('Run `grok inspect --json`') and scopes it to an allowlisted project root, so the agent knows this runs a diagnostic inspection. It does not explicitly differentiate from look-alike siblings such as grok_delegate_doctor or grok_agent_project, so it falls short of a 5.

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

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

No when-to-use guidance, no prerequisites, and no named alternatives among the many grok_* siblings. The only implicit cue is 'Read-only', which signals safety rather than a selection 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=true and openWorldHint=true, so the safety profile is largely covered. The description reinforces this with 'Read-only; no secrets', adding a modest assurance about credential exposure, but discloses nothing further about return shape or enumeration behavior.

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

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

Two short, front-loaded sentences with no filler. The purpose and the CLI backing command come first, followed by the safety note. Appropriately sized for a zero-argument tool.

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 parameterless, read-only enumeration tool with full annotation coverage, the description is complete enough for correct invocation. The only minor gap is the absence of any hint about how results are used (e.g. feeding a model name into grok_delegate).

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 the baseline is 4. The description correctly implies no input is required by framing the action as a simple listing.

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: 'List available models', reinforced by the CLI command `grok models`. This distinguishes it from the agent/session/delegate siblings, which all relate to running or managing agents rather than enumerating models. Lacks any explicit sibling contrast, but the resource is distinct enough to be 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 gives no indication of when to call this tool versus the many grok_agent_* and grok_delegate_* siblings, nor that it is typically used to discover valid model identifiers before delegating work. Usage is only weakly implied by the resource name.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuine non-obvious context by scoping 'read-only' to the permission profile ('does not allow write/edit/shell mutation'), but says nothing about what the call actually creates (sessions, worktrees) or its execution model. Note the tension: the phrase 'Read-only plan variant' sits awkwardly against readOnlyHint=false, though it is explicitly scoped to the executor's permission profile rather than the tool's own 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?

Two tight sentences, front-loaded with the distinguishing fact and the mechanism, with zero filler. Every clause earns its place.

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

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

For a 20-parameter open-world delegation tool this is thin, but 95% schema coverage and present annotations carry most of the load. The core distinction from grok_delegate is covered; output/artifact behavior and session semantics are left to the schema.

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

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

Schema description coverage is 95% across 20 params, so the schema already carries parameter meaning; baseline 3 applies. The description only echoes plan_only=true, adding no syntax, format, or interaction detail beyond the structured fields.

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

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

States a specific variant of a specific tool ('Read-only plan variant of grok_delegate') and pins the mechanism ('plan_only=true'), which cleanly separates it from the write-capable grok_delegate sibling. It clearly conveys that this produces a plan rather than mutations. It stops short of a crisp verb+object statement but is unambiguous.

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

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

The framing 'plan variant of grok_delegate' implies when to reach for it (planning vs execution) but never states it explicitly, names no prerequisites, and gives no exclusions. Usage is inferable only by contrast with the sibling name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces the safety profile with 'Read-only.' More importantly it adds non-obvious behavioral context beyond the annotations: the shape of a completed result (branch, changed_files, commits, diffstat) and the expectation that 'early minutes in git with no worker are normal,' which sets liveness expectations an agent would otherwise misread as a failure.

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

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

Two dense sentences that front-load the core action and then branch on job_id presence. Every clause carries information, though the parenthetical result-field list makes it slightly compressed.

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

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

With no output schema, the description usefully enumerates what a poll returns (state, result fields, phase, elapsed_s), covering the return-value burden. Nothing critical is missing for a two-optional-parameter read tool, though pagination/ordering semantics for the listing mode are left to the schema.

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

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

Schema description coverage is 100%, and both parameters are already documented (job_id provenance and default-to-list, limit default 20). The description restates the job_id source and the omit-to-list behavior, adding no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (poll) and resource (a delegation job) and explicitly ties it to grok_delegate_start as the producer, distinguishing it from the many sibling poll/status tools. An agent can identify 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?

Gives clear conditional guidance: 'With job_id: ...' versus 'Without job_id: newest jobs', so the two modes are unambiguous. It does not, however, distinguish itself from closely related siblings like grok_delegate_status or grok_agent_poll, so the routing choice remains partly inferential.

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 non-read-only, open-world, non-idempotent, non-destructive, but the description adds the concrete workflow consequence: an immediate job_id return, polling requirement, and the safety posture 'Same guarded profile, no push, no merge'. It notably warns that the sync path can leave an empty worktree, which annotations alone would not convey.

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

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

Three sentences, front-loaded with the core behavior and the job_id return, then the routing rationale, then the polling follow-up. No filler; every clause carries operational information.

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

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

For a 20-param background job tool with no output schema, the description covers the return value (job_id), the reason to prefer it, and the next step. It omits what happens on job failure, timeout, or expiry, which would help an agent recovering from an unsuccessful run.

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% across all 20 parameters, so the schema already carries the param semantics (cwd allowlist, lane slug restrictions, lane_verdict behavior, sandbox profiles). The description adds no parameter-level detail, 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 (start) plus the resource (grok_delegate) and the exact mode (BACKGROUND), and explicitly names the sibling it replaces (grok_delegate). An agent can distinguish it from the synchronous variant without opening either schema.

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

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

Gives an explicit when-to-use rule ('for real lanes: a lane runs for minutes'), explains the failure mode of the alternative ('a synchronous call is killed by the client timeout, leaving an empty worktree'), and names the follow-up tool (grok_delegate_poll). 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 declare readOnlyHint and openWorldHint. The description adds key behavioral details: 'auth.json never read' (privacy), and it enumerates what is checked (grok binary/version, auth presence, git, allowed roots/lanes_parent, permission and sandbox profile). It also self-declares 'Read-only' which is redundant with annotations, but the enumeration adds value.

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

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

Two sentences, front-loaded with the purpose and usage trigger. The enumeration is compact. No filler. Could be slightly tighter, but no sentence is wasted.

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

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

For a no-param, read-only diagnostic tool with annotations, the description covers what it reports and when to use it. However, without an output schema, it doesn't describe the shape or format of the health report. For a diagnostic tool, users might expect details on how to interpret results, but the core info is present. Adequate but with a 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?

With zero parameters, the baseline is 4. The description appropriately doesn't discuss parameters since there are none. No further semantic details 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?

States a specific verb+resource: 'Report bridge health'. This distinguishes it from sibling status tools like grok_agent_status. However, it doesn't explicitly contrast with the sibling 'grok_delegate_doctor' which likely serves a similar diagnostic 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?

Gives clear when-to-use conditions: 'before the first job or when a job fails to start'. These are concrete triggers. There's no when-not-to-use guidance or explicit routing to grok_delegate_doctor, which may overlap.

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