grok_task

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

With no annotations, the description carries the full burden. It discloses that the tool runs headlessly using the user's OAuth, returns a list of files changed and commands run (implying modifications), and that background tasks return immediately. It also mentions serial queuing and timeout behavior. It lacks details on error handling or destructive potential, but the implied file changes are sufficient for an agent to infer mutability.

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

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

The description is a single paragraph of 5 sentences, all carrying essential information. It front-loads the main purpose and key usage notes. While it could be slightly more structured with bullet points, it has no wasted words and is easy to scan. The conciseness is good for a tool with complex behavior.

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

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

Given 8 parameters (2 required), no output schema, and no annotations, the description covers critical aspects: when to use background, session continuation, serial queuing, permission mode restrictions, and timeout range. It does not describe the exact return format beyond 'response plus git-verified list of files changed and commands run', which may require the agent to infer structure. Overall, it provides sufficient context for an unfamiliar agent.

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% (all 8 parameters have descriptions), so baseline is 3. The description adds significant value: it explains that background avoids timeouts and requires polling grok_task_result, that session_id carries context, that permission_mode has headless-viable options (auto, bypassPermissions) and warns against acceptEdits, and that timeout_ms has a default with clamp. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Delegate a coding task to Grok Build (headless) as a subagent.' It specifies the verb (delegate), resource (Grok Build), and context (headless subagent in a repository). It also mentions what it returns (response plus git-verified list), distinguishing it from siblings like grok_task_result which is for polling background tasks.

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

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

The description gives explicit guidance on when to use background mode ('tasks likely to exceed ~1 minute') and warns against long synchronous calls ('can hit the MCP client's request timeout'). It also suggests using session_id to continue a previous task and notes that jobs in the same cwd run serially. However, it does not explicitly state when not to use this tool or compare it directly to all siblings (e.g., grok_task_cancel, grok_task_status).

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