Server Quality Checklist

Tool Scores

• grok_modelsA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It adds behavioral context (reads from local cache) but does not disclose return format, potential side effects, or performance implications. For a simple list tool, this is adequate but not rich.

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

  Conciseness5/5

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

  The description is a single, efficient sentence that front-loads the verb and resource, providing all necessary information without any waste.

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

  Completeness4/5

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

  Given the tool's simplicity (no parameters, no output schema), the description is largely complete. However, it does not specify the return format (e.g., array of strings) or behavior when the cache is empty, leaving minor gaps.

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

  Parameters4/5

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

  There are no parameters, so the schema documentation coverage is 100%. The description does not need to add parameter info. A score of 4 is baseline for zero-parameter tools, as the description adds no parameter semantics but is not deficient.

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

  Purpose5/5

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

  The description clearly states the verb 'List' and the resource 'available Grok model IDs', with additional context about the source ('from grok's local model cache'). This distinguishes it from sibling tools which focus on tasks (grok_task, grok_task_cancel, etc.).

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

  Usage Guidelines3/5

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

  The description implies usage for obtaining model IDs but does not explicitly state when to use this tool versus alternatives. Since sibling tools handle tasks, context suggests using this before task creation, but no direct guidance is provided.

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

• grok_taskA
  4.3/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• grok_task_cancelA
  4.4/5.0
  Behavior4/5

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

  No annotations provided, so description carries burden. It discloses that it 'kills the grok process' and 'returns verified partial changes on disk', providing good behavioral insight beyond the basic cancel action.

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

  Conciseness5/5

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

  Two sentences with no wasted words. Front-loaded with action and immediately explains scope and effect.

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

  Completeness4/5

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

  Covers when to use, what happens, and what is returned. Lacks mention of authorization or rate limits, but for a simple cancellation tool with one param, it is adequately complete.

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

  Parameters4/5

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

  Schema description coverage is 100%. The description adds context that job_id refers to a grok_task job and explains the effect of cancellation, offering more than the schema's minimal 'Job ID to cancel'.

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

  Purpose5/5

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

  The description clearly states the action 'Cancel' and the resource 'grok_task job'. It distinguishes from siblings by specifying applicability to queued or running jobs, not finished ones.

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

  Usage Guidelines4/5

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

  The description gives clear context: cancel only queued or running jobs, not finished ones. It does not explicitly mention alternative tools like grok_task_status for checking status, but the guidance is sufficient.

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

• grok_task_resultA
  4.4/5.0
  Behavior4/5

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

  No annotations provided, so description carries full burden. Discloses waiting behavior (max_wait_ms), returns final result or still-running status, safe to call repeatedly, and persistence across restarts. Could mention potential errors or return format.

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

  Conciseness5/5

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

  Three concise sentences, front-loaded with purpose. No redundant information, every sentence adds value.

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

  Completeness4/5

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

  Covers purpose, behavior, persistence, and repeatability. Lacks description of return format or error states, but for a simple 2-param tool with no output schema, it is adequate.

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

  Parameters4/5

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

  Schema coverage is 100%. Description adds value by specifying default and max for max_wait_ms (25000, 50000) and clarifying job_id is from grok_task, enhancing schema info.

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

  Purpose5/5

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

  Clearly states 'Fetch the result of a grok_task job', specifying verb and resource. Distinguishes from sibling tools like grok_task (start), grok_task_status (status), grok_task_cancel (cancel) by focusing on result retrieval for background/timeout jobs.

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

  Usage Guidelines4/5

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

  Provides clear context: use after grok_task completes or times out. Explains safe to call repeatedly and persists across restarts. Lacks explicit when-not-to-use, but sibling differentiation implies alternatives.

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

• grok_task_statusA
  4.5/5.0
  Behavior4/5

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

  Without annotations, the description carries full burden. It discloses non-blocking behavior and that listing includes persisted jobs from previous sessions. No contradictions. Could add more detail about response format or error handling.

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

  Conciseness5/5

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

  Two sentences, front-loaded with key purpose, no extraneous words. Highly efficient.

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

  Completeness5/5

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

  For a simple tool with one optional parameter and no output schema, the description is fully complete. It covers both modes and the behavior across server sessions.

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

  Parameters4/5

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

  The single parameter job_id is described in schema as optional. The description adds value by clarifying that omitting it lists all jobs, while providing it checks a specific job. This enhances understanding beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool checks status of grok_task jobs, with two distinct modes (single job by job_id, or list all jobs). It effectively distinguishes from sibling tools like grok_task (creation), grok_task_cancel, and grok_task_result.

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

  Usage Guidelines4/5

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

  The description provides explicit usage guidance: pass job_id for one job, omit to list all. It implies the tool is for non-blocking status checks without blocking. However, it does not explicitly contrast with siblings or state when not to use, though context signals make alternatives clear.

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