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

The readOnlyHint annotation already covers the read-only nature of the tool. The description adds 'durable' as a behavioral nuance, suggesting the request is a persisted object, but it does not explain failure modes, response shape, or any other runtime behavior. No contradiction with annotations exists.

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 front-loaded sentence with no filler. Every word earns its place, and 'durable' adds a useful connotation of persistence without bloating the text.

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 simple get-by-IDs tool with readOnlyHint, the description is minimally adequate, but it is not complete: there is no output schema, no description of what the returned approval request contains, and no guidance on when this tool is the right choice among siblings. The ambiguity of 'Task' further reduces completeness.

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 needed to compensate, but it only restates the parameter names via 'Task' and 'approval_id'. It does not explain what values are expected, how they relate, or what 'durable approval request' means, leaving the agent to infer semantics from the schema field names alone.

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 uses a specific verb ('Return') and names the resource ('approval request') along with the required identifiers, making the basic purpose clear. However, it does not explicitly differentiate this from sibling tools like approval.respond or audit.get, and 'Task' is slightly ambiguous versus the parameter name task_id.

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 guidance about when to use this tool versus alternatives such as approval.respond or audit.get. The only implied usage is that it retrieves an approval request by IDs, but no context, prerequisites, or exclusion criteria are provided.

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 no annotations provided, the description must disclose behavioral traits itself. It only says the tool 'resolves or escalates', but does not state whether it mutates state, requires permissions, or has side effects like sending notifications. The word 'durable' hints at persistence but is insufficient for an agent to anticipate consequences.

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 sentence, which is concise, but it lacks the detail needed to be functional. It is appropriately short but not informative enough, so it earns a mid-range score for 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?

Given 3 required parameters, no output schema, and no annotations, the description is severely incomplete. It fails to explain what decisions mean, what 'durable' implies, or what happens after resolution/escalation. An agent would be unable to call this tool correctly without external knowledge.

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

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

The schema has 3 parameters (task_id, approval_id, decision) with 0% description coverage, and the tool description does not explain any of them. The enum for decision (ALLOW_ONCE, ALLOW_TASK, DENY, ASK_USER) is self-explanatory, but the description adds no meaning to any parameter, leaving the agent without guidance on how to populate them.

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 uses specific verbs ('resolve' and 'escalate') with a clear resource ('approval request'), making the core purpose understandable. It differentiates from approval.get (which presumably retrieves) and process tools by focusing on the response action. However, it does not elaborate on what 'resolve' or 'escalate' entail in practical terms.

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 guidance is given on when to use this tool versus siblings like approval.get or process tools. There is no mention of prerequisites, context, or scenarios where this tool is appropriate, leaving the agent to infer usage from the name alone.

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 the description does not contradict this. It adds the concept of a sequence cursor, implying incremental access, but does not detail ordering, pagination behavior, or response format. Given annotation coverage, this is minimal but acceptable.

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, well-structured sentence with no filler. It front-loads the core behavior and omits unnecessary detail.

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

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

For a read-only audit getter with no output schema, the description provides a high-level return type but lacks details on pagination, ordering, and the exact response shape. While annotations help with the safety profile, more operational context would improve completeness.

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. It only clarifies 'after_sequence' via the cursor mention, leaving limit and task_id unexplained. The description does not fully resolve parameter meaning.

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

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

The description states a specific verb ('Return'), a clear resource ('Task audit entries'), and a qualifier ('after a sequence cursor'). This differentiates it from all listed sibling tools, none of which relate to audit retrieval.

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 guidance is given on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or common use cases. An agent must infer its role purely from the name and description.

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 no annotations, the description carries the full disclosure burden. It is transparent that the operation is conditional on the current SHA-256 and explains how paths resolve. However, it does not disclose what happens when the SHA-256 does not match, whether the file must already exist, or what the tool returns on success or 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 sentences with no filler: the first front-loads the action and condition, the second gives the path-resolution rule. Every clause adds necessary 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?

There is no output schema and no annotation support, so the description needs to cover failure behavior and parameter semantics. The path-resolution detail is valuable, but the missing SHA-mismatch behavior and lack of explicit old_text/new_text semantics leave an agent under-equipped for safe 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 compensate. It adds meaning for path (worktree vs host OS) and expected_sha256 (the match condition), but it does not explicitly explain task_id or define old_text/new_text as find-and-replace strings. The parameter names are self-descriptive, but the description only partially fills the schema 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?

The description states a specific operation—patch an existing file—and the condition under which it applies (SHA-256 match). It does not explicitly spell out that old_text is replaced by new_text, so some semantics are left to inference, but the resource and action are clear enough to distinguish it from file.write.

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 a concrete path-resolution rule for relative vs absolute paths, but it provides no guidance on when to prefer file.patch over file.write or other sibling tools, and no exclusions or alternative conditions. The SHA-256 check implies optimistic concurrency, but that use case is never 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 readOnlyHint annotation already signals a safe read operation, and the description adds meaningful behavior context: UTF-8 encoding and path resolution semantics. These details affect how the agent should construct calls and interpret results.

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, focused sentence with no filler. The core operation is front-loaded and the important path-resolution caveat is included without unnecessary detail.

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

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

The description covers the operation and path behavior, and readOnlyHint covers the safety profile. However, task_id is left unexplained and there is no output schema or statement about return content, so an agent must infer part of the contract.

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 description partially explains the 'path' parameter via relative/absolute path semantics, but it does not explain the required 'task_id' parameter at all. With 0% schema description coverage, the description is expected to carry more of this burden.

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

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

The description clearly states a specific action and resource: 'Read a UTF-8 file.' It is distinguishable from siblings like file.write and file.patch by the verb and resource, though it does not explicitly name or differentiate itself from file.search.

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 path-resolution rule is a useful usage guideline: relative paths use the Task worktree; absolute paths use the host OS. However, it does not explicitly state when to prefer file.read over alternatives like file.search, nor does it mention any exclusions.

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, so the read-only nature is covered. The description adds two behavioral traits: 'deterministic text matching' indicates reproducible results, and the path resolution rule clarifies how relative vs. absolute paths are handled. However, it does not disclose other potentially important behaviors such as case sensitivity, whether search covers file content or filenames, or how glob interacts with path. Given the annotation covers the safety profile, the added context is useful but not comprehensive.

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

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

The description is two short sentences with no wasted words. It front-loads the primary purpose immediately ('Search files...'), then adds the path resolution detail. It is compact and easy to parse, earning a perfect score for conciseness and 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?

Given the tool has 5 parameters, no output schema, and only a readOnlyHint annotation, the description is insufficient for an agent to fully understand how to use it correctly. It does not explain what the tool returns (e.g., matching file paths, line numbers), how max_results is applied, whether the search is recursive, or what 'deterministic' implies for the agent (e.g., reproducibility for caching). The path resolution is helpful but many operational details are missing, making it incomplete for proper usage.

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. It does add meaning for some parameters: 'text matching' implies the query parameter is the text to search for, 'glob' is a file pattern, and the path resolution sentence explains the path parameter. However, it does not explain max_results (likely a limit) or task_id (likely the task context). Thus it covers 3 of 5 parameters but leaves two unexplained. The description adds partial value but does not fully compensate for the lack of schema 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 action and resource: 'Search files using deterministic text matching and a glob.' This distinguishes it from sibling file tools like file.read (which reads a specific file) and file.write. The mention of 'deterministic text matching' and 'glob' also hints at its specific search behavior. It could be more explicit about what is searched (content vs. filenames) but the core purpose 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 description provides no guidance on when to use this tool versus alternatives. It does not mention conditions like 'use file.read to retrieve a whole file' or 'use file.search to locate files by content.' The only contextual note is about path resolution ('Relative paths use the Task worktree; absolute paths use the host OS'), which is about path interpretation, not usage selection. This leaves the agent to infer when to call this tool.

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

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

With no annotations, the description must carry behavioral disclosure. It does reveal that the operation can replace a fileainer and specifies UTF-8 encoding and path resolution. However, it does not disclose the behavior of the optional overwrite parameter, failure modes, or side effects beyond replacement.

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 concise sentences with no filler. The main action is front-loaded, and path resolution details are placed in a single clarifying second sentence.

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 destructive file-writing tool with no annotations, no parameter descriptions, and no output schema, this is incomplete. The most important gap is overwrite semantics, and the description also fails to clarify task_id or when to prefer file.write over file.patch.

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. It adds meaning to path (relative vs absolute) and content (UTF-8), but task_id and especially overwrite are left undefined. The overwrite parameter is central to the create-vs-replace behavior yet receives no explanation.

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

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

The description states a clear verb and resource: create or replace a UTF-8 file. It is specific enough to be recognizable as a write tool, though it doesn't explicitly differentiate itself from sibling file.patch or file.search.

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 guidance on when to choose this tool over file.patch or other siblings. It explains path semantics but never states the intended use cases, exclusions, or 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?

The destructiveHint annotation already flags mutation, and the description adds useful context: it stages all Task worktree changes and creates a real local commit without push, merge, or deploy. It does not go further to describe side effects, reversibility, or history impact, but the annotation lowers the burden.

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 sentence with no filler. The core action is front-loaded, and the exclusions (push, merge, deploy) are appended efficiently without redundant detail.

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

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

Given the simple two-parameter shape and existing destructive annotation, the description covers the essential operation and its boundaries. It does not explain what counts as 'Task worktree changes', but for the tool's complexity this is a minor gap rather than a blocking omission.

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 does not explain the task_id or message parameters. The names are self-explanatory, but the description fails to compensate for the lack of schema documentation, leaving the agent to infer that message is the commit message and task_id identifies the task.

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 uses a specific verb ('commit') and identifies the exact resource and scope ('all Task worktree changes'), and explicitly excludes push, merge, and deploy. This makes the tool's purpose unambiguous and distinct from siblings like git.diff.

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

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

The description implies when to use this tool: to snapshot all current Task worktree changes as a local commit. However, it does not explicitly state when not to use it or mention alternatives, such as using git.diff to inspect changes first.

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, so the agent knows this is a safe read operation. The description adds useful behavioral context by stating it returns 'structured' changes and includes 'untracked files,' which clarifies the scope of the diff. However, it does not elaborate on the exact structure of the output, pagination, or any limitations, so the added value beyond annotations is moderate.

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 sentence that is front-loaded with the primary action and resource, and it efficiently adds the key detail about untracked files. There is zero wasted text, and every word contributes to the meaning. It is highly concise and well-structured.

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

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

The tool is simple (one parameter, no output schema) and has read-only annotations, so the description covers the essential aspects: what it returns and a key edge case (untracked files). It does not describe the return format in detail, but given the lack of an output schema, some ambiguity remains. Still, for a straightforward diff tool, the description is largely sufficient for an agent to call it correctly.

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

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

Schema coverage is 0%, meaning the parameter has no description in the schema, so the description must compensate. The description mentions 'Task worktree changes,' which implies the task_id parameter selects the task, but it never explicitly names or describes the parameter's role. Since the schema already shows a single required string with minLength 1, the description adds minimal meaning but does not fully explain how task_id is used (e.g., whether it's a UUID or a human-readable name). This is adequate but not thorough.

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 a specific verb ('Return') and a precise resource ('structured Task worktree changes and unified diff'), adding the detail 'including untracked files' to further scope the output. It distinguishes itself from all sibling tools, none of which offer diff functionality, so an agent can immediately identify this as the diff tool.

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

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

The description implies usage by naming the purpose (returning changes/diff) but provides no explicit guidance on when to use it versus alternatives. Since no sibling tool performs diffs, the usage is self-evident, but there are no stated exclusions or context such as 'use before commit' or 'only when a task is active.' This meets the 'implied usage' bar but nothing more.

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

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

Beyond the destructiveHint annotation, the description adds 'best-effort' (indicating the operation may not succeed) and clarifies scope ('its Linux process group'). This gives the agent useful behavioral context. It doesn't describe failure modes or return behavior, but the core destructive trait and nuance are covered.

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, focused sentence with no wasted words. The key qualifier 'Best-effort' is front-loaded, and the scope is stated clearly. It is highly concise and well-structured.

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 and minimal description, the agent does not know what the tool returns on success or failure. There is no mention of idempotency, error handling, or what happens if the process is already terminated. For a destructive operation, this leaves important gaps. The description is too brief to be fully self-contained.

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

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

The schema has 0% description coverage, so the description must explain the parameters. It does not explicitly map task_id and process_id to their roles, though the names are somewhat self-explanatory. The description only says 'cancel a running Task process', implying task_id identifies the task and process_id the process, but this is not made explicit. This is insufficient compensation for the schema 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?

The description states a specific verb ('cancel'), a resource ('a running Task process and its Linux process group'), and a qualifier ('Best-effort'). This clearly distinguishes it from siblings like task.cancel (which cancels a whole task) and process.start/status/output. An agent can tell exactly what this tool does.

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?

Usage is implied: use this to cancel a running process within a task. However, there is no explicit guidance on when not to use it or how it differs from task.cancel or other process-related tools. No alternatives are mentioned, so the agent must infer the appropriate context.

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

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

The readOnlyHint already signals a safe read, and the description adds the useful behavioral trait that output is read incrementally via a pull cursor rather than returned as a single snapshot. It does not contradict the annotation, though cursor/EOF mechanics are left unspecified.

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, tightly worded sentence with the verb and resource front-loaded. There is no filler or redundant detail.

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

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

For a tool with no output schema and no parameter descriptions, the definition is thin: an agent still does not know what a pull cursor returns, how to start or advance it, or what end-of-stream/empty output looks like. The readOnlyHint covers safety but not invocation details.

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 needs to compensate. It only ties the 'pull cursor' idea to the cursor concept and generally references process output, but it never explains the roles of task_id and process_id or how the cursor is initialized and advanced.

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 a specific verb ('Read'), a specific resource ('process stdout/stderr'), and a distinguishing mechanism ('incrementally from a pull cursor'). This makes it easy to separate from siblings like process.status or process.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?

The description gives no explicit guidance about when to use this tool instead of alternatives such as process.status. The incremental pull-cursor phrasing implies a streaming use case, but no when/when-not conditions or named alternatives are provided.

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 no annotations, the description carries full responsibility for behavioral disclosure. It mentions 'asynchronous' and the two modes, which are useful, but it does not disclose side effects (e.g., whether a task record is created), failure modes, or what happens if both argv and shell are provided. It also lacks any note about authentication or resource 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?

The description is a single, front-loaded sentence that states the core action immediately. It is concise and free of filler. However, it is almost too terse, omitting important details that would not bloat it significantly.

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

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

Given the tool's complexity (5 parameters, nested env object, no output schema, no annotations), this description is insufficient. It does not explain how argv and shell interact, whether one is required, what task_id references, or what the return/status mechanism is. The sibling tools like process.status and task.create imply a workflow, but the description provides no context to navigate it.

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. It adds minimal meaning by hinting at argv vs shell modes, but it does not explain task_id (beyond being required), cwd, env, or the relationship between argv and shell. The description does not help an agent understand how to populate these parameters correctly.

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 uses a specific verb 'start' with a clear resource 'asynchronous Task process' and mentions two execution modes (argv or shell). This distinguishes it from siblings like process.output and process.cancel, which clearly handle output and cancellation. However, it does not clarify what a 'Task process' is or how it relates to task.create/resume, leaving some ambiguity.

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 guidance is provided on when to use this tool versus alternatives like task.create or task.resume, nor any exclusions. The agent must infer usage solely from the name and sibling set. It does not mention prerequisites (e.g., must a task exist first?) or when to prefer argv over shell.

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 readOnlyHint annotation already signals a safe read operation. The description adds the phrase 'execution metadata,' which hints at additional data beyond simple status, but it does not elaborate on what that metadata includes or whether the operation can fail. Since the annotation covers the primary safety profile, a 3 is reasonable.

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, efficient sentence that front-loads the core purpose. There is no redundancy or fluff, though it is extremely minimal. It earns a 4 for being concise and directly actionable.

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

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

The tool has only two required parameters and no output schema, yet the description omits any explanation of what 'execution metadata' includes, how to interpret the response, or when to call this versus sibling tools. For a simple status query, an agent needs more context to use it correctly, especially given zero schema descriptions.

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 provides no explanation for task_id or process_id. The agent is left to infer their meaning from the names alone. With no schema descriptions and no additional clarification, the tool fails to convey parameter semantics.

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

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

The description states a clear action ('Return') and a specific resource ('current status and execution metadata for a Task process'). It distinguishes from siblings like process.output and process.cancel by implying a read-only status query, though it does not explicitly name alternatives.

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

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

No guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or conditions that would route an agent to process.status instead of process.output or task.resume. Usage context is entirely absent.

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, but the description adds a useful specific behavioral guarantee: it does not modify the working tree. This goes beyond the generic read-only hint and gives the agent confidence about side effects. It does not detail what information is returned or whether any operations are cached, but for a simple read-only tool this is adequate.

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 sentence that is front-loaded with the action and resource, and contains zero filler. Every word contributes to the meaning.

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

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

For a one-parameter read-only tool, the description plus schema cover the essential invocation details. The lack of an output schema means the return format is not specified, but 'inspect' implies a readable result, and the absence of more detail is not a major obstacle for a simple inspection tool.

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

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

Schema description coverage is 100%, so the parameter is already fully documented by the input schema. The description adds no additional meaning about 'path' beyond what the schema states. Per the rubric, this is a baseline 3.

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

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

The description uses a specific verb ('Inspect') and resource ('local Git repository'), and adds a clear non-destructive scope ('without modifying its working tree'). It does not explicitly differentiate from close siblings like git.diff or file.read, so it falls short of a 5, but it is far from vague or tautological.

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

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

The description implies when to use the tool: whenever you need to inspect a local Git repository without side effects. However, it provides no explicit guidance about when to choose repo.inspect over alternatives such as git.diff or file.read, and no exclusions or 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 no annotations, the description does useful behavioral work by clarifying that installation is a storage-only operation with no execution side effect. It does not, however, disclose what happens if source_id already exists, how 'replace' affects existing state, or any permission requirements. The key safety trait is present, but the mutation semantics are incomplete.

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, with the core action in the first sentence and the critical non-execution caveat in the second. There is no filler, redundancy, or wasted wording.

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

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

The tool is simple (four scalar parameters, no output schema), and the core purpose is clear. However, the absence of parameter descriptions, annotations, and output schema leaves gaps around 'source_id' and 'replace'. A careful agent would not know how to choose values for those fields or what to expect back.

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 mentions none of the four parameters by name. 'repo_url' can be loosely inferred from 'Git-backed,' but 'source_id', 'ref', and 'replace' remain undefined, and 'replace' has important behavioral implications. The description does not compensate for the empty schema.

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

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

The description names a specific action ('Install'), a specific resource ('a Git-backed skill source'), and a destination ('AgentDock state'). It also preempts confusion with execution tools by explicitly stating it stores instructions only and does not execute a skill or run an LLM. This is enough to distinguish it from siblings like skill.list, skill.update, and process.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?

The description implies the tool is used when a Git-backed skill source needs to be added to AgentDock state, and it rules out execution use cases. However, it never names alternatives such as skill.update or process.start, nor does it state when to prefer one. This is useful but implied rather than explicit 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 annotation already marks readOnlyHint=true, and the description adds valuable context by explicitly stating the tool lists skills 'without invoking or executing them'. This reassures the agent that the operation is safe and has no side effects beyond enumeration.

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 sentence that conveys the core behavior and a key safety trait without any filler. Every word 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?

The tool is simple and the read-only annotation covers safety, but the single parameter source_id is completely unexplained and no return format is described. For a basic list operation this is minimally adequate, but the parameter gap prevents full completeness.

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 does not mention source_id at all. With no schema-level explanation and no compensation in the description, the agent has no guidance on what source_id means or how it affects the list.

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 uses a specific verb and resource: 'List installed server-side skills'. It clearly states what the tool does and differentiates it from siblings like skill.search and skill.read by focusing on listing installed skills rather than searching or reading content.

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

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

The description makes the use case clear: use this when you need to enumerate installed server-side skills. It does not explicitly exclude alternatives or name sibling tools for other scenarios, but the intended context is obvious and no misleading guidance is present.

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 readOnlyHint annotation already signals that this is a safe read operation, and the description adds valuable behavioral context beyond that: the tool returns instructions for the chat model to follow, not server-executable code. This changes how the agent should process the output and prevents a potentially harmful misinterpretation.

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 with no filler. The core action is front-loaded ('Read the recommended installed SKILL.md or one of its supporting files'), and the second sentence earns its place by giving essential processing guidance.

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

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

The description covers the main action and the nature of the return value (instructions to follow), which is useful given there is no output schema. However, source_id and resource_path are left undefined, no output format is described, and there is no explicit guidance for selecting this skill-read tool over file.read. It is adequate but leaves clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate, but it only vaguely suggests that skill_name selects the installed SKILL.md and that a supporting file may be read via another parameter. The optional source_id parameter is not explained at all, and resource_path is never explicitly named or defined. Some meaning is added, but not enough for a tool with three undocumented parameters.

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 starts with a specific verb and object: 'Read the recommended installed SKILL.md or one of its supporting files.' This clearly identifies a read operation on skill files and separates it from sibling tools like skill.install, skill.update, and skill.search. The skill-based scope also distinguishes it from generic file.read.

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

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

It gives actionable context: use this after a skill is recommended or installed, and follow the returned instructions. It also tells the model what to do when those instructions reference another skill or local resource—read that resource explicitly rather than treating the skill as executable server code. It does not explicitly name alternative tools or state when not to use this tool, so it falls just short of a 5.

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

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

The annotation readOnlyHint=true is consistent with the description's 'Search' verb, so there is no contradiction. The description adds useful context about what is searched ('name, category, and description') and the scope ('installed server-side'), but it does not describe matching behavior, ordering, pagination, or return format. The annotation already covers the safety profile, so 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.

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

The description is a single, front-loaded sentence with no filler. It is efficient and easy to parse, though some useful details about parameters and behavior were omitted in favor of brevity.

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, minimal annotations, and 0% schema description coverage, the description carries most of the burden for understanding the tool. It leaves the return payload undefined, does not explain 'source_id', and provides no guidance on how 'limit' affects results, so it is not complete enough for confident 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 compensate. It clarifies that 'query' matches against name, category, and description, but it says nothing about the optional 'limit' or 'source_id' parameters. Those parameters remain undocumented in both the schema and the 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 states a specific verb ('Search'), a specific resource ('installed server-side skills'), and the search dimensions ('name, category, and description'). It is clear, but it does not explicitly distinguish the tool from the closely related skill.list or skill.read siblings, 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?

The description implies usage when an agent needs to find installed skills by text-based fields, but it does not explicitly state when to prefer this over skill.list or skill.read, nor does it provide exclusions. The 'installed server-side' scoping adds some context, but no when-not guidance is given.

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 no annotations, the description carries the behavioral disclosure burden. It does reveal that the tool reinstalls from a recorded Git URL/ref and reports commit changes, which is meaningful. However, it does not disclose side effects, permissions, failure modes, or what happens if the source is unchanged.

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, front-loaded sentence with no filler. It efficiently combines the action, source, and result in one sentence.

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 tool with no output schema and no annotations, the description conveys the core behavior and expected result. Still, it leaves source_id semantics, exact return format, and side-effect expectations implicit, so 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 coverage is 0% and the description does not explicitly define source_id beyond implying it identifies an existing skill source. It provides only indirect semantic value and no guidance on format, source, or how to obtain valid values.

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

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

The description states a specific action ('Reinstall an existing skill source'), a concrete mechanism ('from its recorded Git URL/ref'), and an observable outcome ('report whether the source commit changed'). It clearly differentiates from siblings like skill.install by emphasizing 'existing' and 'recorded Git URL/ref'.

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?

Usage context is implied: it is for updating an existing skill source, not installing a new one, but the description never explicitly says when to use this tool over skill.install, skill.read, or other skill tools. There are no explicit alternatives or exclusions.

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

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

Beyond the destructiveHint annotation, the description adds meaningful behavioral detail: the operation is 'best-effort', it stops running processes, and it preserves the worktree. This tells the agent exactly what will be affected and what will not, which is directly useful for risk assessment.

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 sentence with the action front-loaded and zero filler. Every clause contributes operational information: active scope, best-effort behavior, process stopping, and worktree preservation.

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 tool with no nested objects and no output schema, the description plus schema is sufficient to invoke it correctly. It covers the key decision factor (active task) and the observable effect, so nothing essential 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 schema only documents task_id as a non-empty string, so the description's 'ACTIVE Task' qualifier adds useful selection semantics: the provided id must reference an active task. It does not explain how to obtain the id or what happens with an invalid/inactive one, but for a single obvious parameter this is a reasonable contribution.

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 uses a specific verb ('Cancel') with a specific resource ('Task') and a scope qualifier ('ACTIVE'), making the tool's purpose unmistakable. 'ACTIVE' also distinguishes it from finishing or cleaning up a completed/abandoned task, and the action word separates it from process.cancel.

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 clearly states the precondition ('ACTIVE Task') and the expected effect ('stopping its running processes while preserving the worktree'), so an agent knows when cancellation is appropriate. It does not explicitly mention alternatives like process.cancel, task.finish, or task.cleanup, so it stops short of a full when/when-not comparison.

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 include destructiveHint=true, and the description aligns by saying 'Remove the worktree'. It adds valuable context beyond the annotation by clarifying exactly what is destroyed (the worktree) and what is preserved (durable metadata), which mitigates the destructive impact. No contradiction with annotations.

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

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

The description is a single, tightly worded sentence that front-loads the core action and key conditions. Every word contributes value, with no fluff or repetition. It is an exemplar of concise, effective tool documentation.

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

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

The description covers the core purpose and destructive scope, but lacks details such as behavior when the task is not in COMPLETED/CANCELLED state, idempotency, prerequisites (e.g., task must exist), or any error conditions. Given the tool's simplicity and the presence of a destructive annotation, it is adequate for typical usage but leaves edge cases undefined.

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

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

The input schema has one parameter (task_id) with 0% description coverage, and the description does not elaborate on the parameter at all. It does not explain how to obtain or format task_id, nor does it clarify the parameter's role beyond the schema's minimal type constraint. Given the low schema coverage, the description fails to compensate, leaving the parameter semantics largely undocumented.

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 action ('Remove the worktree') and the resource ('of a Task'), with explicit preconditions (COMPLETED or CANCELLED). It also specifies what is preserved ('durable Task metadata'), making it distinct from sibling tools like task.cancel or task.resume. The purpose is unambiguous and 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?

The description provides a clear condition for use: only for tasks that are COMPLETED or CANCELLED. This implies when to use it, though it does not explicitly name alternatives or state 'do not use for active tasks'. It gives enough context for an agent to infer appropriate usage, but falls short of explicit routing to sibling tools.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool creates a 'clean detached Git worktree' and that the task is 'ACTIVE' and based on 'source HEAD', which conveys key behavioral context. However, it does not mention potential side effects (e.g., whether existing worktrees are affected) or required permissions, but the core action is clearly described.

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, front-loaded sentence that efficiently states the purpose and key environment details. Every word adds value, and there is no redundancy or unnecessary 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?

The tool is relatively simple (one parameter, no output schema), and the description provides enough for an agent to know what the tool does. However, it lacks usage guidance (when to call it vs. alternatives) and does not mention any prerequisites or side effects beyond the worktree creation, making it only partially complete for fully informed 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?

The schema has one parameter (repo_path) with a description ('Path inside the source Git repository'), giving 100% schema coverage. The tool description adds context that the worktree is based on source HEAD, but it does not significantly expand on the meaning of repo_path beyond what the schema already states. Thus, it meets the baseline without substantial added value.

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: creating an ACTIVE coding task in a clean detached Git worktree based on source HEAD. The verb 'create' combined with the specific resource ('coding task') and environment details distinguishes it from sibling task operations like resume, finish, and cancel.

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 explicit guidance is given on when to use this tool versus alternatives. While sibling names suggest different lifecycle stages, the description does not mention any conditions, prerequisites, or exclusions (e.g., when to use task.resume instead).

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 carry destructiveHint=true, so the bar is lower; the description adds that this is a state transition to COMPLETED and implies no process termination or commit happens here. It does not explain irreversibility or downstream effects of finishing, which would be useful for a destructive operation.

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 sentence with no filler; the key action and precondition are front-loaded. Every word 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 one-parameter tool with no output schema, this is nearly complete: it names the action, target, and required precondition. A brief note on what happens once completed—such as that the task can no longer be resumed—would fully close the loop with siblings like task.resume.

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?

There is only one parameter, task_id, and schema description coverage is 0%; however, the description's reference to 'an ACTIVE Task' makes the parameter's meaning obvious and clarifies it must identify an active task. No format details are needed for this single self-describing identifier.

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

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

The description states a specific verb ('mark'), resource ('ACTIVE Task'), and target state ('COMPLETED'), which clearly differentiates it from siblings like task.cancel and task.cleanup by the resulting state. The precondition 'after processes stop and the worktree is committed' further anchors its role.

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 explicitly says to invoke after processes stop and the worktree is committed, giving the key temporal condition. It does not name alternatives such as task.cancel for abandoned tasks or task.resume for unfinished work, so the when-not-to-use guidance is implicit rather than explicit.

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

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

Annotations include readOnlyHint=true, which partially covers the safety profile. The description adds that the tool returns restored process metadata, but it fails to clarify whether the operation has side effects (e.g., actually resuming execution). The verb 'Resume' creates ambiguity against the readOnlyHint, though it is not an outright contradiction. No details about idempotency, state changes, or error behavior are provided.

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, efficient sentence that front-loads the action and resource. Every word contributes meaning, with no redundant filler. Its brevity does cause missing guidance, but that is captured in other dimensions.

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 should explain the return value; it mentions 'restored process metadata' but not its structure. For a one-parameter tool, this is mostly sufficient, but the behavioral ambiguity around whether the tool mutates task state or only reads it leaves an agent uncertain in the context of a lifecycle-oriented sibling set.

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 description names the only parameter, task_id, in the phrase 'by task_id', which overcomes the 0% schema description coverage. However, it does not explain the expected format, how to obtain a valid task_id, or any additional constraints beyond the schema's minLength. For a single string parameter, this is adequate but minimal.

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 a specific verb ('Resume'), a resource ('durable Task'), and the expected result ('return restored process metadata'). This is enough to understand the core action and distinguish it from sibling tools like task.create, task.cancel, task.finish, and task.cleanup. However, it does not explicitly clarify whether 'resume' means actually restarting execution or simply retrieving resume metadata, leaving some ambiguity.

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 guidance on when to use this tool versus alternatives such as task.create or process.start, nor any mention of prerequisites (e.g., task must be paused). The single sentence provides no usage context, exclusions, or selection criteria.

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 no annotations provided, the description carries the full burden. It discloses that invalid jumps fail closed and that the durable history records the transition, which are important behavioral traits. It doesn't mention side effects like whether the transition is reversible or what happens to open decisions, but the core failure semantics are disclosed.

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

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

Two sentences with no waste. The core constraint (only advance after a phase boundary) is front-loaded, and the failure semantics are stated compactly. Every sentence 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?

The tool has six parameters, no output schema, and no annotations. The description explains the transition semantics but doesn't clarify what the 'event' values mean, how 'open_decisions' interacts with the fail-closed behavior, or what a successful response looks like. For a state-advancing tool, this is adequate but leaves gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It doesn't explain any of the six parameters, but the schema itself has descriptive enums (event names, session_span, route_clarity) and required fields. The description adds no parameter-level meaning, so a baseline 3 is appropriate given the schema's self-explanatory enums.

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

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

The description states a specific verb ('advance') and resource ('guided-development state'), and clarifies that advancement is only valid after a skill reaches an explicit phase boundary. It distinguishes itself from workflow.start/list/update/guide by focusing on state transitions, though it doesn't explicitly name a sibling alternative.

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

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

The description gives clear when-to-use guidance: only after the recommended skill has reached an explicit phase boundary, and never to skip unresolved decisions. It doesn't explicitly name alternatives or exclusions, but the context is strong enough for an agent to decide when to call it.

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

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

Annotations already declare readOnlyHint=true, and the description adds the crucial behavioral detail that the tool does not execute the recommended skill—only reads state and recommends. It also hints at persistence ('durable'). While it doesn't cover error cases or the exact output format, it supplements the annotation meaningfully without contradiction.

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

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

Two sentences with zero redundancy. The core action is front-loaded ('Read durable guided-development state and recommend the next workflow skill'), followed immediately by concrete usage triggers and a follow-up instruction. Every sentence 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 simple tool with one parameter and no output schema, the description covers purpose, usage, and the follow-up action. It does not specify the exact return format or behavior when no state exists, but the instruction to 'read the recommended skill' implies the output is a skill reference. Minor edge cases are omitted, but overall it is nearly complete for its simplicity.

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 does not mention repo_path at all. The single parameter's purpose must be inferred from the tool name and context; it is never explicitly defined. Given the low schema coverage, the description should have compensated by explaining that repo_path identifies the repository for which guidance is sought, but it fails to do so.

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 a specific verb ('read') and resource ('durable guided-development state'), and explicitly notes it recommends a skill without executing it. It distinguishes itself from sibling tools like workflow.advance (which likely executes) and skill.list/read (which handle skill retrieval directly), making the tool's role 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 explicit trigger conditions ('whenever the user says continue, asks what to do next, or says they do not know the next development step') and instructs the agent to then read and follow the recommended skill. It implicitly differentiates from starting a new workflow or advancing an existing one, providing clear when-to-use guidance.

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

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

The readOnlyHint annotation already covers safety, and the description adds useful context about durability and cross-chat recovery. It does not describe return shape, ordering, filtering behavior, or any edge cases, but for a read-only list tool the annotation lowers the burden.

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 well-structured sentence that front-loads the operation, states the resource, and explains the purpose. There is no filler or redundant restatement of the tool name.

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 simple read-only list tool, the description is mostly adequate, but the sole parameter is undocumented and there is no output schema to clarify the return shape. A little more detail about include_done and the kind of workflow objects returned would make this fully self-sufficient.

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 does not mention include_done at all. The parameter name is self-explanatory at a basic level, but the description fails to clarify what 'done' means in this workflow context, whether the default excludes done items, or how the flag affects the recovered 'active projects.'

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

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

The description opens with a specific verb and resource: 'List durable guided-development workflows.' It immediately clarifies the tool's role and gives a concrete purpose—recovering active projects across chats—so an agent can distinguish it from workflow.start, workflow.advance, and other mutation-oriented siblings.

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

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

The description gives a clear usage context: use this tool before asking the user to repeat context, especially across chats. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full routing 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?

No annotations exist, so the description must carry the full transparency burden. It discloses that 'existing state is protected unless replace=true', and mentions 'first-use setup plus deterministic routing are enforced' – useful behavioral hints. But it does not explain the concrete side effects (e.g., whether it writes to the repo, needs auth, or returns a workflow ID), leaving gaps an agent would need to call it safely.

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

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

The description is compact – three sentences that cover purpose, usage, parameter hints, and key behavior in a front-loaded way. There is no fluff or tautology. Slight denseness in the third sentence keeps it from a 5, but it is well structured.

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

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

For a tool with 6 parameters, no annotations, and no output schema, the description gives a reasonable overview but not enough for complete autonomous invocation. It clarifies when to use it and some behavior, but terms like 'first-use setup' and 'deterministic routing' are left undefined, and there's no guidance on expected return values or failure modes.

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. It adds meaning for session_span and route_clarity by instructing the agent to classify them from the conversation/repository, and for replace by explaining it overrides protected state. However, it gives no added meaning for goal, repo_path, or decisions_settled beyond what their names and types imply, so compensation is partial.

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

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

The description states a specific verb and resource: 'Start durable guided-development state for a new software goal.' It also provides the trigger condition ('when the user wants development guidance or does not know the next step'), which clearly separates it from siblings like process.start or task.create. The word 'durable' and the focus on 'development guidance' make the tool's role distinct, even without naming alternatives directly.

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 explicit usage context: 'Use this when the user wants development guidance or does not know the next step.' This tells the agent when to invoke the tool. However, it does not name alternative tools or exclusion conditions (e.g., when to use workflow.update or workflow.guide instead), so it lacks the when-not guidance needed for a 5.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It states that progress is persisted, scoped to the current phase, and durable across chats. However, it does not disclose whether existing state is overwritten or merged, what prerequisites exist, or whether there is any confirmation/return 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?

The description is two focused sentences with no filler. The core action and scope are front-loaded, and the usage guidance earns its place without redundancy.

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 state-persisting tool with six parameters, no annotations, and no output schema, the description covers the central purpose and typical use case. But it omits the role of the required repo_path parameter, the meaning of session_span and route_clarity, and any side effects or return behavior, leaving notable gaps for an 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 description coverage is 0%, so the description must compensate. It maps 'open decisions', 'routing observations', and 'artifact paths' to likely parameters like open_decisions, route_clarity, and artifacts. However, repo_path, note, and session_span are left implicit, and the description does not explain enum semantics beyond what parameter names suggest.

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 uses a specific verb ('persist') and resource ('progress inside the current guided-development phase'), and explicitly scopes the action with 'without crossing a phase boundary.' This distinguishes it from workflow.advance and other siblings without being tautological.

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

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

The description gives clear use guidance: 'Use it to keep open decisions, routing observations, and artifact paths durable across chats.' It implies when this tool is appropriate rather than a phase-advancing alternative, though it does not explicitly name sibling tools or exclusions.

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