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

With no annotations provided, the description carries the full burden. It reveals support for two acceptance mechanisms (legacy and done_by_agent), but does not disclose side effects, permissions, or return values, leaving some behavioral gaps.

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 that front-load the purpose and condition. Every word earns its place; no redundant or vague phrasing.

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 mutation tool with two string params and no output schema, the description covers the core purpose and precondition. However, it lacks details on error conditions or the exact effect, making it adequate but not comprehensive.

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

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

Schema coverage is 100% with basic descriptions for goal_id and subgoal_id. The description does not add additional semantic meaning for these parameters beyond what the schema provides, thus baseline of 3 is appropriate.

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 action ('Accept a subgoal') and specifies the precondition ('after all associated tasks are accepted by audit_task'). It also notes support for two status formats, distinguishing it from siblings like reject_subgoal.

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 explicitly states when the tool should be used: after audit_task has accepted all associated tasks. This provides clear context, though it does not explicitly list alternatives or when not to use 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 indicate destructive behavior. The description adds value by mentioning validation of expected_sha256 before applying, which is a key safety guard. It also enumerates supported operations, though it does not detail failure modes or atomicity.

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

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

Two sentences, front-loaded with the primary purpose, followed by key details. No wasted words.

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

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

The tool has 4 required parameters and no output schema, yet the description does not mention review_id, which may be required in some operations. It also leaves unspecified what happens on SHA mismatch or overall return values. Given the complexity, this is a notable gap.

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

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

Schema coverage is 80% and each parameter has a description. The description reinforces the meaning of expected_sha256 (validation) and the operation types, but does not add significant syntax or format details beyond the 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 clearly states the tool applies JSON patch operations to a file within a Direct session's repo_path, using a specific verb and resource. It also lists the supported operation types, distinguishing it from file creation/deletion tools.

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 for editing existing files in a Direct session, but no explicit when-to-use or alternatives are given. While siblings like create_file and delete_file are present, no exclusions or comparisons 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?

The description adds behavioral context beyond annotations: 'Performs 16 deterministic checks' and 'returns pass/warn/fail decision.' While readOnlyHint is false, the description does not claim read-only behavior, so there is no contradiction. It could further clarify side effects, but for an audit tool the added detail is useful.

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 sentences, front-loaded with the verb and resource, and contains no filler. Every sentence earns its place: the first states what it does, the second explains behavior and prerequisite.

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 a single parameter and no output schema, the description sufficiently covers purpose, behavior, and prerequisite. It lacks details about the 16 checks or what pass/warn/fail mean, but these are not critical given the simplicity of the tool and existing annotations.

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 already fully describes the single parameter 'session_id' with 100% coverage. The description adds contextual meaning by stating the session must be finalized first, which is valuable beyond the schema and helps the agent understand valid input.

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: 'Independently audit a Direct session's changes' with a specific verb ('audit') and resource ('session's changes'). It also distinguishes itself from siblings like 'audit_task' and 'safe_audit_direct_session' by focusing on Direct sessions and providing a pass/warn/fail decision.

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 prerequisite: 'Requires session to be finalized first.' This gives context on when to use the tool, but it does not explicitly mention when not to use it or alternative tools, so it stops 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?

No annotations provided, so description carries full burden. Discloses key behaviors: writes independent-review.md, returns evidence-backed failures, highlights possible heuristic false positives, and separates manual-verification items. Does not mention auth or rate limits, but behavior is well-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?

Description is concise with front-loaded action ('Independently audit a task's outputs'). Each sentence adds value, though minor redundancy in listing checks could be tightened.

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 task complexity and no output schema, the description sufficiently explains the tool's behavior and output. Covers what is checked and how results are structured, leaving little ambiguity for the 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 has 100% description coverage for the single parameter ('Task ID to audit'). Description adds no further meaning beyond schema; baseline 3 is appropriate.

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?

Clearly states the tool independently audits a task's outputs with specific checks (status, result.md, test.log, etc.) and produces independent-review.md. Distinguishes from siblings like 'diagnose_task' by its comprehensive verification scope.

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?

Describes what the tool does ('Independently audit a task's outputs') but does not explicitly state when to use it over alternatives like 'diagnose_task' or 'safe_audit'. No when-not guidance or prerequisites.

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 clarifies that cancellation is a request, the runner performs actual termination, and the server does not directly kill PIDs. This adds valuable non-obvious context beyond what the tool name implies.

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 sentences with no wasted words. The purpose is stated first, followed by clarification of behavior. It is appropriately sized for the tool's simplicity.

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 no output schema and no annotations, the description explains the cancellation mechanism but lacks information about return values, error handling for invalid task IDs, or behavior if the task is already complete. It is sufficient for a simple tool but not comprehensive.

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 100% coverage with a description for 'task_id'. The description does not add any additional meaning or syntax guidance beyond what the schema already provides, so baseline score of 3 is appropriate.

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 it requests graceful cancellation, distinguishing it from forcefully killing a process. It explicitly mentions the runner performs termination and the server never kills a PID from task files, which differentiates it from sibling 'kill_task'.

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?

While the description implies it's for graceful cancellation, it does not explicitly state when to use this tool versus 'kill_task' or other alternatives. No prerequisites or usage context 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?

Without annotations, the description carries full burden. It discloses sequential checking, read-only GET via node:https, network error handling as 'not_checked', no premature success claims, and no shell commands for remote queries. Lacks mention of authorization or side effects.

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

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

Concise, front-loaded with version and purpose. Every sentence adds value without redundancy. Well-structured for quick comprehension.

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

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

Describes stages and behavior but lacks explanation of return format or output structure. Since no output schema exists, this is a gap. Still covers core logic adequately.

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 covers all 6 parameters with descriptions. The description adds context about stage progression and remote query behavior but repeats some schema info (e.g., version required for published_verified). Baseline 3 due to full schema coverage.

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 'Verify release readiness across five sequential stages' and lists them. Though it doesn't explicitly differentiate from sibling tools like release_check or release_verify, the purpose is specific and actionable.

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 vs alternatives. Does not state prerequisites or when not to use it. The description only explains what it does, not context for selection.

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 indicate a write operation (readOnlyHint: false) and not destructive. The description adds the prerequisite of enableDirectProfile: true, which is useful, but it doesn't disclose what creating a session does (e.g., whether it changes files, what session state occurs). With annotations present, the bar is lower, and this description provides only marginal additional context beyond them.

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, each earning its place. The first states the action and purpose, the second states a critical prerequisite. No fluff, properly front-loaded.

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 3-parameter creation tool with no output schema, the description covers the basic purpose and prerequisite but omits workflow context such as what the session enables, how it connects to direct patching, and what the return value is. Given sibling tools like finalize_direct_session and request_direct_review, a bit more context would help.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions the config requirement but doesn't add any detail about the parameters themselves (title, repo_path, expected_changes) beyond their schema descriptions. It neither helps nor hurts.

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 creates a 'Direct editing session' for applying patches directly, which is a specific verb+resource combination. However, it doesn't explicitly distinguish this from sibling tools like request_direct_review or create_task, so it stops short of full differentiation.

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 minimal usage context: it says the session is for ChatGPT to apply patches and requires enableDirectProfile: true, but doesn't explain when to prefer this over alternatives or when not to use it. No exclusions or alternative references 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds meaningful behavioral context beyond that: files are bounded, the target and parent are revalidated, sensitive content is blocked, and existing targets are never overwritten. This discloses important side effects and constraints, going beyond the annotations without contradicting them.

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 sentences, front-loaded with the primary purpose, and every clause earns its place by adding key behavioral or contextual information. No filler or 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?

Given the tool's complexity (4 parameters, no output schema) and the presence of annotations, the description covers the essential purpose, key constraints, and behavior. It lacks explicit success/error return details and does not specify when review_id is required, but these are minor gaps for a create operation and the description is sufficiently complete for an AI to select and invoke the 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?

The input schema covers 75% of parameters with descriptions; the description adds context that helps interpret the parameters: 'bounded' and 'sensitive content blocked' clarify content constraints, 'revalidated' and 'repository-relative' inform path semantics, and 'inside an active Direct session' gives meaning to session_id, which lacks a schema description. This adds value beyond the schema without fully detailing each parameter.

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 verb 'Create' and the resource 'a new bounded UTF-8 text file inside an active Direct session.' It distinguishes from sibling tools by specifying 'bounded', 'UTF-8', 'inside an active Direct session', and 'existing targets are never overwritten', making its purpose unambiguous relative to file operations like apply_patch, move_file, and delete_file.

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 clear context: it is for creating new text files within an active Direct session, with revalidation and sensitive-content blocking. It implies when not to use (when updating/overwriting an existing file) via 'never overwritten' but does not explicitly name alternative tools. This is clear context without exclusions, matching a score of 4.

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 provided, but description discloses side effects: creates a structured directory with specific files. It adds behavioral context beyond the schema. Minor lack of detail on permissions or reversibility.

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 front-loaded purpose and context about output structure and sibling tools. Every sentence is valuable and efficient.

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?

Fairly complete given complexity: mentions files created (.patchwarden/goals/{goal_id}/ with GOAL.md, GOALS.md, goal_status.json). No output schema, so return values not described, but overall adequate.

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

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

Schema coverage is 100%, so baseline 3. Description does not add significant meaning to parameters beyond what schema already provides.

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?

Description clearly states 'Create a Goal Session' with specific verb and resource, and mentions generating a structured directory, distinguishing it from siblings like list_goals and read_goal.

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?

Explicitly recommends using list_goals and read_goal for enumeration and inspection, providing clear context for when not to use this tool. Does not explicitly state exclusions but is sufficient.

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 burden. It discloses atomic steps and dependency requirement, but lacks details on failure rollback, idempotency, or auth needs. 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?

Two concise sentences with no wasted words. Purpose and key behavioral trait are front-loaded. Efficient and clear.

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?

Despite 19 parameters and no output schema, the description only covers atomicity and dependencies. It does not explain return values, error conditions, or parameter relationships, leaving gaps for a complex 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 baseline is 3. Description adds no new parameter-level insight beyond what the schema already provides; it merely restates dependency behavior.

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?

Description clearly states the tool creates a subgoal and immediately launches an associated task, with an atomic sequence. It distinguishes from sibling tools like create_goal and create_task by combining both actions.

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?

Provides context about dependencies and the atomic nature, implying when to use it. However, no explicit exclusions or alternatives are mentioned, so it's not a perfect 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?

No annotations are provided, so the description bears full responsibility. It discloses behavior about stale watchers ('A stale watcher preserves the task but returns execution_blocked and directs the client to health_check') and instructs to call wait_for_task until terminal, which are beyond basic functionality.

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 4 sentences, front-loads the purpose, and every sentence contributes unique information. It is efficient and well-structured 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?

Given 16 parameters and no annotations, the description covers critical workflows but omits context for many parameters (e.g., plan_id, inline_plan, test_command). It is sufficient for basic use but incomplete for full parameter integration.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by explaining the interplay between execution_mode and assessment_id, and the requirement of source_task_id for rollback_scope_violation template, thus going beyond the 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 'Create a repo-scoped task from exactly one source.', which is specific and distinguishes it from sibling tools like create_subgoal_task. It also mentions templates and assess_only flow, further clarifying its purpose.

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

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

The description provides explicit guidance on when to use certain templates ('For ChatGPT, prefer the guarded inspect_only, feature_small, or fix_tests template when it fits') and outlines the two-step assess_only/execute workflow. It does not list alternatives or exclusions but gives clear 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 description adds behavioral detail beyond the annotations by explicitly stating the hash and confirmation requirements, indicating that the delete will not proceed without them. It also clarifies the bounded single-file constraint. The annotations already flag destructiveHint=true, so the description enriches rather than contradicts this.

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, dense sentence that front-loads the core action and immediately follows with necessary constraints. Every word earns its place, making it highly concise without sacrificing clarity.

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 deletion tool, the description covers the essential context: what it deletes, the safety requirements, and unsupported operations. It does not mention return values or error behavior, but no output schema exists and the scope is narrow. The description is sufficiently complete for an agent to use the tool 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 low (20%) with only confirm_delete described. The description adds meaning by referencing 'current SHA-256' (expected_sha256) and 'confirm_delete=true', and implying session_id via 'Direct session'. However, it does not explain path, session_id, or review_id, leaving some parameter semantics unclear.

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 with a specific verb and resource: 'Delete one bounded regular text file inside a Direct session.' It distinguishes itself from siblings like create_file, move_file, and sync_file by specifying file deletion and the 'Direct session' scope, plus the exclusion of directories.

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 clear context on when to use the tool by listing prerequisites ('Requires the current SHA-256 and confirm_delete=true') and what is unsupported ('directories and recursive deletion are unsupported'). It does not name alternative tools, but the exclusions and requirements guide appropriate usage.

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 fully covers behavioral traits: read-only, multi-signal evidence, PID reuse protection, and refusal to call PID-alive tasks active when other signals are stale. No contradictions.

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 concise (3 sentences) and front-loaded with the core purpose. Every sentence adds value; no wasted words.

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

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

Given no output schema, the description covers return types and behavior well. It lacks mention of error cases (e.g., invalid task_id), but overall it's fairly complete for a 2-param tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters adequately. The description does not add extra meaning to parameters beyond what the schema provides, meeting the baseline.

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

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

The description clearly states the tool diagnoses a running or collecting_artifacts task using multi-signal evidence, specifying output types and read-only nature. It distinguishes from siblings like get_task_status by emphasizing multi-signal conservative diagnosis.

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 explains when to use (diagnosing ambiguous task states) and highlights the conservative approach. It implies not to rely on this when a simple status is sufficient, but lacks explicit when-not-to-use or alternative tool references.

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 discloses key behaviors: forceful removal, branch deletion, status archiving, and safety guards. It could be more explicit about irreversibility, but the information is reasonably transparent for a mutation tool.

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?

Very concise: three sentences cover purpose, actions, usage, and safety. No unnecessary words, front-loaded with key 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?

Given no output schema and minimal annotations, the description covers purpose, usage, and safety. It lacks error conditions or permissions, but is complete enough for a straightforward discard operation.

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

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

Schema description coverage is 100%, so the schema already explains parameters. The description adds a safety note about guards but no additional semantic meaning beyond what is in the schema. Baseline score of 3 is appropriate.

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 discards an isolated git worktree, specifying the actions (removes worktree, deletes branch, archives status) and distinguishes it from sibling tools like merge_worktree. The verb 'discard' and resource 'isolated git worktree' are specific and 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?

Explicitly states 'Use when a subgoal is rejected or abandoned,' providing clear context. While it does not list alternatives or when not to use, the usage guidance is sufficient for the intended scenario.

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?

Describes read-only nature, default hiding of high-risk tools, and return format; no annotations so description carries full 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?

Two efficient sentences front-loading purpose, version, and key behaviors without waste.

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?

Covers return format, filtering, safety; no output schema but description suffices for a search tool with 6 well-described params.

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?

Adds context beyond schema by linking filters to behavior (e.g., includeHighRisk overrides riskCeiling), despite 100% schema coverage.

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?

Clearly states it discovers tools via natural-language query, distinguishes from siblings like explain_tool and invoke_discovered_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?

Implies usage for discovery before invocation, mentions read-only nature and high-risk filtering, but lacks explicit 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 description marks the tool as read-only and lists the metadata fields it returns. It also explains the optional includeSchema parameter behavior. No annotations are provided, but the description fully compensates.

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. First sentence details output; second provides usage guidance and read-only flag. No wasted words.

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

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

Given no output schema, the description adequately lists the metadata fields returned (title, summary, risk level, etc.) and explains the optional schema inclusion. Sufficient for understanding the tool's output.

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

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

Schema coverage is 100% with descriptions. The description adds context: name accepts aliases, includeSchema defaults false for minimal output, which enhances understanding beyond the 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 clearly states the tool's purpose: to expand a single tool's metadata including title, summary, risk level, tags, aliases, etc. It distinguishes from sibling tools like discover_tools by specifying usage context.

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?

Explicitly states when to use: 'Use after discover_tools to understand a specific tool before calling it.' Also notes it is read-only, guiding the agent on safe usage.

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 should disclose behavioral traits. It only outlines the report content but omits details like side effects (none expected), permissions, error handling, or output format.

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?

Single concise sentence that front-loads the verb and resource, listing key contents without redundancy. Every word adds value.

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 no output schema, the description partially covers output by listing components but lacks specifics on format or structure. It is adequate for a single-parameter tool but not fully 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 100% and the parameter description is clear. However, the tool description adds no extra meaning beyond the schema, meeting baseline expectations.

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 defines the tool as exporting a structured final report for a Goal session, specifying the aggregated components (subgoal completion, task evidence, risk summary). This distinguishes it from sibling tools like summarize_goal_progress or export_handoff.

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 explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or compare with similar tools like summarize_goal_progress.

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 are provided, so the description must disclose behavioral traits. It specifies the output file location (.patchwarden/goals/{goal_id}/handoff.md) and the content included, which is transparent about the main side effect (file write). It lacks details on overwrite behavior or error handling but is otherwise 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?

The description is concise: three sentences that front-load the purpose, then detail content and output path. No wasteful or redundant phrases; every sentence provides essential information.

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

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

For a simple export tool with one parameter and no output schema, the description fully explains the action, output content, and destination. It is self-contained and leaves no obvious gaps for the 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?

The input schema only gives a minimal description for goal_id ('Goal ID'). The description adds context by showing how goal_id is used in the output path and tying it to the goal session, going beyond the schema's brief 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 clearly states the verb 'Export' and the resource 'handoff.md document' for transferring a Goal Session, listing contents and output path. It is specific and distinct from sibling tools like export_task_evidence_pack.

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 says 'for transferring a Goal Session to a new conversation,' providing clear usage context. However, it does not explicitly exclude alternative tools or provide when-not-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?

With no annotations, the description carries full burden. It discloses outputs (evidence.json, EVIDENCE.md) and important exclusions (stdout, stderr, logs, diff, sensitive files), giving the agent a clear picture of what the tool does not include. However, it does not mention whether the tool is read-only or has side effects, which would enhance transparency.

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

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

Two sentences, front-loaded purpose, with clear specification of outputs and exclusions. Every sentence adds value, no wasted words.

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

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

Given the tool's simplicity (2 params, no output schema), the description is sufficient for an agent to understand what it does and what it produces. It could briefly mention it's a read-only operation, but overall covers the key aspects.

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 already describes both parameters with high coverage (100%). The description reinforces that lineage_id comes from run_task_loop and implies max_items bounds the pack, but adds no new parameter-level details beyond the 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 clearly states the tool exports a bounded evidence pack for a run_task_loop lineage, specifies the output files (evidence.json, EVIDENCE.md), and lists exclusions (stdout, stderr, logs, diff, sensitive files). The verb 'export' and resource 'evidence pack' are specific, and the context distinguishes it from sibling tools like get_task_log_tail.

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 after run_task_loop by referencing the lineage, but does not explicitly state when to use this tool or when to use alternatives like get_task_lineage or get_task_log_tail. No when-not-to-use guidance is 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?

Annotations provide no safety hints (all false), so the description carries the burden. It discloses side effects (capture snapshot, generate artifacts, mark finalized) and the ordering constraint, but lacks details on reversibility, failure modes, or required permissions. 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?

Two concise sentences, front-loaded with the action, and every word earns its place. No redundancy or 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 single-parameter tool with no output schema, the description covers the process steps and the critical ordering relationship. It lacks explicit prerequisites (e.g., snapshot existing) and alternative safe variant, but overall it is sufficiently complete for the tool's 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 100% for the only parameter session_id, and the description adds no additional parameter-specific meaning. Baseline 3 applies as the schema already fully documents the parameter.

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?

Description uses specific verb 'Finalize' with resource 'Direct session', enumerates concrete actions (capture after snapshot, generate diff/summary/change artifacts, mark finalized), and distinguishes itself from sibling audit_session via the explicit ordering constraint 'Must be called before audit_session'. This fully clarifies what the tool does and how it differs.

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?

Explicitly states 'Must be called before audit_session', providing a clear usage sequence and context. However, it does not mention when not to use it or alternative tools like safe_finalize_direct_session, so it stops short of full usage 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 description discloses conditional behavior (returns different data depending on readiness), which adds value. However, it lacks information on side effects, permissions, rate limits, or return format. Since no annotations are provided, the description carries the full burden, and it is only partially transparent.

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

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

A single, front-loaded sentence conveys the core action and an important conditional. Every word serves a purpose, and there is no redundancy or 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?

Given the tool's single parameter and lack of output schema, the description is mostly sufficient but leaves ambiguity about what 'diff evidence' and 'structured availability and watcher evidence' mean. Additional context about the conditions for each return type 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 coverage is 100% with a brief description for 'task_id'. The tool description does not add any additional meaning or constraints beyond what the schema already provides, so it meets the baseline for high coverage but adds no extra 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 verb 'read' and resource 'task diff evidence', establishing a specific purpose. It adds nuance by describing an alternative return when evidence is not ready. While it distinguishes from most siblings, it could be more precise about what 'diff evidence' entails.

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 on when to use this tool versus alternatives like 'safe_diff_summary' or 'get_task_log_tail'. The description implies it is used to check readiness, but does not specify conditions or provide 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?

Without annotations, the description carries the burden of behavioral disclosure. It only states 'Read', implying no side effects, but lacks details on permissions, rate limits, or potential errors. The description is minimal and does not enrich the agent's understanding.

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 with no wasted words. It is front-loaded with the essential information.

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

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

For a simple read tool with one parameter and no output schema, the description is adequate but incomplete. It does not specify what the tool returns, which is needed since there is no output schema. More context would help the agent understand the output format.

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

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

Schema coverage is 100%, so the schema already documents the parameter. The description adds no additional meaning beyond stating 'by its plan_id', which repeats the schema. Baseline 3 is appropriate.

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 verb 'Read', the resource 'saved plan', and the parameter 'plan_id'. It distinguishes from siblings like 'save_plan' or 'read_goal' due to the specific resource.

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 such as 'save_plan' or 'list_goals'. There is no context on prerequisites 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?

With no annotations, the description fully covers behavioral traits: it reads a file, returns safe defaults if missing, and explicitly states what the policy does not expand. No hidden side effects or assumptions.

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, front-loaded sentences. The first states the core purpose, the second adds critical behavioral constraints. 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 read tool with one parameter and no output schema, the description thoroughly explains what it does, edge case behavior (missing policy returns defaults), and limitations (what it doesn't affect). No 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?

The schema coverage is 100% with a clear description for repo_path. The tool description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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 reads a specific file (.patchwarden/project-policy.json) and returns a summary, with a clear verb (Read) and resource. It distinguishes itself from siblings by focusing on policy reading.

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 (to read project policy) and provides important context about what the policy does not affect, but lacks explicit 'use this when' or alternative 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?

With no annotations, the description carries full burden. It discloses conditional behavior but lacks details on side effects, permissions, or error cases.

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?

Single, front-loaded sentence with no wasted words. Efficiently conveys core functionality.

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 essential behavior. Lacks details on error states but is sufficient for basic understanding.

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

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

Schema coverage is 100%, so description adds minimal value. The parameter task_id is described only as 'Task ID' with no extra context from 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 clearly states it reads result.md or returns structured availability and watcher evidence, with a specific condition (task not terminal). This differentiates it from siblings like get_result_json and safe_result.

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 (based on task terminality) but does not explicitly compare to alternatives or provide when-not-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?

No annotations provided, so description carries full burden. It states it reads result.json but fails to disclose read-only nature, error handling (e.g., missing task_id), permission requirements, or any side effects. For a tool with no annotations, this is insufficient.

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 concise sentence front-loads the primary function. No fluff, but could briefly mention what 'structured result.json' entails without becoming verbose.

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 simplicity (1 param, no output schema), the description covers the core purpose. However, missing behavioral context like error scenarios or output format reduces completeness. Moderately adequate but not fully comprehensive.

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

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

Schema coverage is 100% with task_id described as 'Task ID'. Description adds context that result.json is structured and for deterministic acceptance, but does not elaborate on the parameter itself. Baseline 3 is appropriate as description provides some added context beyond 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?

Description clearly states it reads structured result.json for deterministic task acceptance. Verb 'Read' is specific, resource 'result.json' is precise, and purpose 'deterministic task acceptance' distinguishes it from general result retrieval tools like get_result.

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 on when to use this tool versus sibling tools like get_result or get_task_status. The context for 'deterministic task acceptance' is implied but not explained, leaving ambiguity.

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 provided, so description carries full burden. It says 'safe summary' indicating non-destructive, and lists exclusions, but lacks details on permissions or side effects.

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

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

Single sentence that effectively communicates core purpose. Front-loaded and efficient.

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 no output schema and no annotations, the description is minimal. It does not describe the return format or structure of the summary, leaving some ambiguity for the agent.

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

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

Schema coverage is 100% with clear parameter descriptions. Tool description adds some context about being bounded but does not significantly enhance parameter meaning beyond 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?

Clearly states the tool reads a bounded safe summary for a run_task_loop lineage. Explicitly lists what it does not return, distinguishing it from siblings like get_task_log_tail.

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?

Implies usage for getting a summary rather than full logs, but does not explicitly name alternative tools or provide when-to-use/when-not-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?

Discloses automatic secret redaction, default/max line limits (80/200), and the tail-only behavior. Without annotations, the description carries full burden and covers key behavioral traits, but omits details like error handling or performance impact.

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: first conveys purpose and behavior, second gives usage guideline. No redundant words, easy to parse. Front-loaded with key 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?

Given no output schema or annotations, the description adequately covers purpose, behavior, and usage. It assumes output is raw text lines, which is reasonable. Lacks explicit mention of return format or error cases, but remains largely complete for a simple read 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 baseline is 3. The description reiterates file enum values and default/max for lines, adding some context but not significantly beyond the schema. No additional semantics for task_id or redact beyond defaults mentioned.

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 explicitly states the verb 'Read', the resource 'task log file', and the scope 'last N lines' along with specific log file options (stdout/stderr/test/verify). It also distinguishes from read_workspace_file, making its purpose very clear.

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?

Provides explicit guidance: 'Use this instead of read_workspace_file to avoid triggering platform content filters on log output.' Also implicitly says not to use for full files via 'Always returns tail only — never the full file.'

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?

Description indicates a read operation on progress.md, which is non-destructive. However, it does not disclose behavior like file existence requirements, output format, or whether partial reads occur. With no annotations, the description provides adequate but not detailed transparency.

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, front-loaded with the key action, and no unnecessary words. Every part is relevant.

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 tool with one parameter and no output schema, the description covers the core function. It could mention output details (e.g., returns raw content) for full completeness, but overall it is 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?

The single parameter task_id is described in the schema as 'Task ID', and the description adds no extra meaning. Schema coverage is 100%, so baseline 3 applies.

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

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

Description clearly states 'Read progress.md' and lists specific information (task phases, heartbeat, current command). This distinguishes it from sibling tools that read other files or statuses, providing a specific verb and resource.

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 like get_task_status or get_task_summary. The description does not mention prerequisites, context, 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?

No annotations provided, and description does not disclose whether the tool is read-only, side-effect-free, or requires specific permissions. It only lists output fields.

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?

Single sentence listing multiple fields efficiently. No extra words, but could be slightly more 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?

Covers what the tool returns, but lacks context on prerequisites, error handling, or how it differs from similar tools. Adequate for a simple status check.

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

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

Schema coverage is 100% with a single parameter well-described. Description adds no extra insight beyond what the schema already provides.

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?

Description clearly states it checks task status and enumerates specific fields (execution phase, watcher health, etc.), making it distinct from siblings like get_task_progress or get_task_summary.

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 over alternatives, prerequisites, or exclusions. The description only lists what it returns without 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?

Without annotations, the description carries the full burden. It discloses key behaviors: real-time reading during execution, fallback to result.md after completion, and default line count. This is transparent beyond the schema.

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 concise with three sentences: purpose, behavior, and usage states. It is front-loaded and contains no fluff.

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 simplicity, schema coverage, and lack of output schema, the description covers essential behavioral context (states, fallback, default). It is adequately complete for a tail-read tool.

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

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

Schema coverage is 100%, with both parameters described. The description adds the default value (80) which is already in the schema. Thus, the description provides minimal additional meaning over the 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 clearly states the tool reads the last N lines of agent stdout/stderr, specifying the action and resource. However, it does not differentiate from sibling tools like get_task_log_tail, which may have similar functionality.

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 context on when it works (pending, running, completed tasks) and mentions the fallback behavior. It lacks explicit when-not-to-use or alternative tools, but the guidance is sufficient for typical usage.

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 are provided, so the description must disclose behavior. It explains what each view returns, but doesn't explicitly state that the operation is read-only or non-destructive. The name 'get' implies safety, but more explicit transparency would be better.

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

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

Two sentences, front-loaded with the core purpose, and every word contributes meaning. No redundant 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?

Given 3 parameters and no output schema, the description covers the view usage well but does not describe the return structure in detail. It mentions 'structured acceptance evidence' but lacks specifics on format or content.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by advising when to use each view value, which goes beyond the schema's enum descriptions. This strategic guidance improves parameter understanding.

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 'Return structured acceptance evidence', which clearly specifies the verb and resource. It distinguishes from sibling tools by focusing on acceptance evidence summaries, and the mention of view modes adds specificity.

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 advises to use view=compact first and upgrade to standard only when needed, providing clear heuristics. However, it does not compare this tool to alternative siblings like get_task_log_tail or get_diff.

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?

Without annotations, the description must fully disclose behavior. It mentions a dual-mode behavior (read log vs return evidence) but does not explain the conditions, side effects, or required permissions. The behavioral traits are inadequately 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 extremely concise (one sentence) but is unclear and under-specified. The phrasing 'while it is not ready' introduces confusion without earning its place. Conciseness alone does not compensate for lack of clarity.

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 conditional behavior and lack of output schema, the description is incomplete. It does not explain what 'structured availability and watcher evidence' means, when each mode triggers, or the return format. Essential context is missing.

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

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

Schema coverage is 100% for the single parameter, so the baseline is 3. The description does not add any meaning beyond the schema's 'Task ID' label. No extra semantics are provided.

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 specifies 'Read test.log' which indicates a resource, but the conditional clause 'or return structured availability and watcher evidence while it is not ready' is ambiguous and unclear. It does not clearly differentiate from sibling tools like get_task_log_tail or get_result.

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 siblings such as get_task_log_tail, get_result, or others. The description lacks context about prerequisites 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable nuance: agent availability is executable-only unless an explicit provider probe is requested, and self_diagnostic provides expanded read-only evidence. This goes beyond annotations without contradicting them.

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 sentences, front-loaded with the main purpose and followed by a key caveat and parameter tip. Every sentence adds value, and there is no redundant or filler 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 health check tool with no output schema, the description sufficiently covers what is checked and how to request expanded evidence. It does not describe return format, but the simple nature and strong annotations reduce the need for more. It could mention typical use cases, but overall it is adequately complete.

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

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

Schema description coverage is 100% for the single parameter, with detailed explanation of the self_diagnostic option. The tool description lightly repeats this and adds 'read-only', but does not introduce new semantic information. Baseline 3 is appropriate given the schema carries the parameter documentation.

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

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

The description clearly states the tool checks multiple subsystems (MCP catalog, watcher, supervisor, workspace, agents) with the specific verb 'Check'. It is unambiguous but does not explicitly differentiate this tool from similar read-only diagnostic siblings like safe_status or diagnose_task.

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. The only usage advice is parameter-level ('Use detail=self_diagnostic'), which does not help with tool selection. Sibling tools with overlapping purposes (safe_status, diagnose_task) are not mentioned or distinguished.

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 provided; description lacks disclosure of side effects (e.g., overwriting, idempotency) or validation behavior. For a mutation tool, more transparency is needed.

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?

Single sentence, no redundancy. Efficiently conveys core purpose.

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

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

No output schema or return value description. Lacks error handling context. Despite moderate complexity, description omits important details for a complete understanding.

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

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

Schema coverage is 100%, baseline 3. Description adds 'mapping task files to scope hints and acceptance criteria' but does not significantly enhance parameter understanding beyond 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?

Description clearly states verb 'import', resource 'Spec Kit tasks into a Goal session as subgoals', and mapping details. Distinguishes from siblings like accept_subgoal by being a specific import operation.

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 vs alternatives (e.g., create_subgoal_task). No mention of prerequisites like goal existence or when not to use.

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 provided. Description mentions 10 security checks and that it cannot call itself recursively, adding behavioral context. However, it does not disclose outcomes of checks, error behavior, or side effects beyond the listed constraints.

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?

Single paragraph is front-loaded with version and purpose. Lists 10 security checks concisely without extraneous words. Every sentence 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?

Covers security checks, token requirement, and recursive call prohibition, but lacks details on return value (no output schema) and error behavior. For a security-sensitive tool, additional context on success/failure outcomes 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 coverage is 100% but description adds value: explains token lifecycle (single-use, 10-minute expiration) and condition for assessmentId (required for workspace_write/release risk tools), enhancing understanding beyond schema property 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?

Description clearly states it invokes a previously discovered tool using a discoveryToken, with a specific verb 'invoke' and resource 'discovered tool'. It distinguishes from the sibling discover_tools which provides the token.

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?

Explicitly states prerequisite: 'The token must be obtained from discover_tools first.' Provides clear context for when to use, but does not include explicit when-not-to-use or alternatives beyond the prerequisite.

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 partially bears the transparency burden. It discloses that the runner validates and kills only its child process, which is a key behavioral trait. However, it omits details about side effects (e.g., task status change, reversibility) and authorization requirements.

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

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

Two sentences front-loaded with action. No redundant words or phrases. Every sentence contributes essential information.

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

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

For a simple one-parameter tool, the description covers the core function and a key behavioral nuance. However, it does not explain the return value or whether the tool is idempotent, which are relevant for an agent deciding to invoke or retry.

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% (task_id has a clear description). The tool description adds minimal additional meaning beyond saying 'terminate a task', which is already implicit. Baseline score of 3 is appropriate since the schema does the primary documentation.

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

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

The description clearly states the tool terminates pending or running tasks, with a specific verb (terminate) and resource (pending/running task). It also adds nuance about validation and child process ownership. However, it does not explicitly distinguish from the sibling tool 'cancel_task', which would provide clearer differentiation.

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 for pending or running tasks and mentions the runner validates and kills its own child process. It does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like 'cancel_task' for gentler termination.

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 description explicitly states it is a read-only check, does not contact a model provider or test account balance, and explains provider_status remains not_checked. This fully discloses behavioral traits, especially since no annotations 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 two sentences, concise and front-loaded. Every sentence adds value: first sentence lists actions, second explains a specific behavioral detail. Zero waste.

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 no output schema, the description could be more complete about the return value or format of the agent list. It mentions reporting the config path but does not describe the full output structure, leaving some ambiguity for the 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?

There are no parameters, so the description does not need to add parameter semantics. With 0 parameters, a baseline of 4 is appropriate, and the description adds context about what the tool does without 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 clearly states the tool lists agents from the active runtime config, verifies executable and model-argument wiring, and reports the config path. This specific verb+resource set distinguishes it from siblings like read_workspace_file or create_task.

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 for read-only checks without contacting providers, but it does not explicitly state when to use this tool versus alternatives like read_workspace_file or when not to use 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?

Since no annotations are provided, the description bears full responsibility. It explicitly states it lists all sessions and is sorted, implying a read-only, non-destructive operation. It does not disclose any side effects, which is appropriate for a list tool.

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 front-loads the version and action. It is concise with no redundant information; every part adds value.

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 no parameters and a simple listing functionality, the description adequately defines the tool. It mentions return fields and sorting. However, it does not specify if there is pagination or a maximum number of results, which could be relevant for a list-all 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?

There are no parameters, so the schema coverage is trivially 100%. The description adds no parameter information, but none is needed. The baseline for 0 parameters is 4.

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 it lists all Goal Sessions and specifies the returned fields (goal_id, title, status, subgoal counts, last update time). It uses the verb 'list' and the resource 'Goal Sessions', distinguishing it from sibling tools like read_goal (single goal) and create_goal.

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 this tool is for retrieving an overview of all goal sessions, but does not explicitly mention when to use alternatives (e.g., read_goal for a specific goal). There is no guidance on exclusions or context for when not to use 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?

With no annotations, the description carries full burden. It discloses a key behavior: 'Archived history is excluded by default'. However, it does not mention other behaviors, such as whether the operation is read-only, sorting order, or performance considerations.

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 concisely conveys the tool's purpose, key filters, and default behavior (exclude archived). No wasted words; all information is front-loaded.

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 no output schema, the description gives some hint of return fields (watcher state, pending reasons) but lacks details on ordering, pagination, or the full shape of the response. It's adequate for a list tool with 5 well-documented parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by referencing the filter parameters (status/repo/active/history) and mentioning computed fields (watcher state, pending reasons) that are not in the schema, enriching understanding of what the tool returns.

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 lists recent tasks with specific filters (status, repo, active, history) and mentions additional derived fields (watcher state, pending reasons). It distinguishes from sibling tools like get_task_status (single task) and get_task_lineage (history) by focusing on filtering a list.

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 on when to use this tool vs alternatives. It does not mention when not to use it or provide context like prerequisites or common patterns. For example, it doesn't say 'For a single task's status, use get_task_status'.

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 destructiveHint=false, and the description adds useful behavioral context by specifying that sensitive files are excluded. This goes beyond the annotation information without contradicting it.

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 the verb 'List' immediately. It is concise with a valuable parenthetical caveat, containing no unnecessary words.

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

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

For a simple listing tool with one optional parameter and rich annotations, the description is largely adequate. It lacks an explicit return format, but the verb and resource make the output predictable. A slightly more detailed description of the path semantics or return structure would be beneficial.

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 covers the single parameter 'path' with a clear description and default, achieving 100% coverage. The tool description adds little beyond implying the path is relative to the workspace, so the schema carries the semantic weight.

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 the specific verb 'List' with the resource 'workspace', and clarifies it covers 'files and directories' while excluding 'sensitive files'. This clearly distinguishes it from sibling tools like read_workspace_file, list_agents, and list_tasks.

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

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

The description provides clear context for when to use the tool: to enumerate workspace contents. It does not explicitly mention alternatives or when-not-to-use, but the behavior is straightforward and the parenthetical about sensitive files adds a relevant constraint.

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?

Discloses that it updates worktree_status.json to 'merged' and that merge failures preserve the worktree for manual inspection. Without annotations, this is good but could mention additional behavior like permission requirements or commit creation.

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 plus version number, front-loaded with purpose and usage. No extraneous 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?

Covers purpose, usage timing, state changes, and failure behavior. Lacks any mention of return value, but no output schema exists. Nearly complete for a simple tool.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. Description does not add extra meaning beyond the 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?

Clearly states verb 'Merge' and resource 'isolated git worktree's changes back into the main workspace'. Distinguishes from siblings like discard_worktree by focusing on merging accepted work.

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?

Explicitly says 'Use after a subgoal task (created with isolate_worktree=true) is accepted', providing clear context. Lacks explicit 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?

Annotations already indicate destructive behavior (destructiveHint=true). The description adds valuable behavioral context by specifying that it creates only 'one new directory level' (non-recursive), which is a key constraint, and details the blocked paths. This goes beyond the annotation without contradicting it, although it omits edge-case behavior like what happens if the directory already 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 concise, with two sentences that front-load the core purpose and then provide necessary constraints. Every word adds value, and there is no redundant or filler content.

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 tool's main purpose, preconditions, and restrictions, but it lacks important context for a complete understanding: there is no explanation of the return value (no output schema), no clarification of what constitutes an 'active Direct session,' and no mention of the review_id parameter. For a simple tool like mkdir, this is moderately incomplete but not severely so.

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 compensate. It implies the 'path' parameter and 'session_id' via context, but the 'review_id' parameter is completely unexplained. For an agent to invoke the tool correctly, it needs to know the purpose of each parameter, especially review_id, which is not obvious from the name or context.

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 function with a specific verb ('Create'), resource ('directory level'), and scope ('inside an active Direct session'). It distinguishes itself from sibling file operations like create_file and move_file by focusing solely on directory creation, and the word 'new' clarifies it does not modify existing directories.

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 clear usage context: it operates within an active Direct session, requires parent directories to already exist, and explicitly lists blocked path categories. While it does not name alternative tools directly, the exclusions and prerequisites effectively guide when to use this tool versus creating files or touching restricted paths.

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

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

The description adds meaningful behavior beyond the destructiveHint annotation, explicitly stating 'never overwrites the target' and requiring the current source SHA-256. This conveys safety semantics and concurrency checks, though it does not explicitly mention source deletion, which is implied by 'move'.

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, zero filler. The first sentence states the primary action, the second adds essential conditions, making it optimally concise and front-loaded.

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 tool with no output schema, the description covers core semantics, safety constraints, and session scope. It lacks an explicit statement that the source is deleted and does not describe error behavior if the target exists, but 'move' implies removal and 'never overwrites' implies failure, so it is reasonably 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?

With 0% schema description coverage, the description compensates by explaining the expected_source_sha256 parameter ('Requires the current source SHA-256') and target_path behavior ('never overwrites the target'). Other parameters like session_id and source_path are left to self-explanatory names, but the critical safety semantics are covered.

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 'Move one bounded regular text file within a Direct session,' a specific verb+resource+scope that clearly differentiates it from sibling tools like create_file, delete_file, and sync_file. The constraints 'bounded' and 'regular text file' add precision beyond the tool name.

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

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

It provides clear context: use when you need to move a bounded regular text file in a Direct session, and it states a key precondition ('Requires the current source SHA-256'). However, it does not explicitly name alternatives or scenarios to avoid, so it stops 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?

With no annotations, the description carries the burden. It states 'Read' which implies a safe, read-only operation, and lists what is read. No hidden side effects are suggested.

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. First sentence defines action and scope, second sentence provides usage guidance. No redundant information.

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

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

For a simple read tool with one parameter and no output schema, the description fully covers purpose, content, and usage. No gaps given the complexity.

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

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

The schema already describes goal_id as 'Goal ID from list_goals or create_goal'. The description adds context by saying 'Use after list_goals', which reinforces the parameter origin. Baseline 3 for 100% coverage, with minimal 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?

Clearly states it reads full Goal Session details including specific files and subgoals. Differentiates from sibling 'list_goals' by specifying use after listing.

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?

Explicitly says 'Use after list_goals to inspect a specific goal', providing clear context for when to use. Does not mention exclusions or alternatives beyond list_goals.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context: sensitive files are blocked, and Direct mode scopes reads to the session's repo_path and returns sha256, going beyond the annotations.

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

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

The description is two sentences, each earning its place: the first defines the core action, the second adds constraints and mode-specific behavior. There is no redundant wording or filler.

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

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

Given a simple 2-parameter tool with read-only annotations and no output schema, the description covers purpose, constraints, and mode-specific return behavior. It is fully sufficient for an agent to correctly select and invoke the 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?

The input schema fully describes both parameters (100% coverage), providing a baseline of 3. The description adds meaning by noting that sensitive files are blocked, enriching the semantics of the 'path' parameter beyond the schema 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 clearly states the tool reads a file within the workspace, using the specific verb 'Read' and resource 'file within the workspace'. It also mentions sensitive file blocking and Direct mode behavior, distinguishing it from sibling tools that write, delete, or list files.

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 clear context for when to use the tool: for reading files, with special behavior in Direct mode when session_id is provided. It does not explicitly name alternative tools or exclusions, but the context is sufficient for agent selection.

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 are provided, so the description bears full responsibility for behavioral disclosure. It qualifies the tool as 'bounded read-only' and lists exclusions, but does not detail authentication needs, error behaviors, or the format of the recommendation. While adequate, it lacks depth on potential side effects or limitations.

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 sentences: one for the primary purpose and one clarifying what it does not do. It is front-loaded with the key action, contains no redundant information, and efficiently conveys the tool's scope.

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 five parameters (two required) and full schema coverage, the description sufficiently outlines the tool's purpose and boundaries. However, the return value ('recommendation') is unspecified, and without an output schema, the agent might need more detail on what the recommendation contains. Still, the description is mostly complete for a read-only routing 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?

The input schema has 100% description coverage, so the baseline is 3. The tool description adds no additional meaning to the parameters; it does not explain how they influence the recommendation. Given full schema coverage, the description does not need to elaborate, but it also provides no extra 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 returns a 'bounded read-only agent routing recommendation for a repo-scoped task', specifying a specific verb and resource. It distinguishes itself from siblings by explicitly listing what it does not do: 'Does not start an agent, create a task, or read logs.' This differentiation is clear and direct.

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 usage guidance by stating what the tool does not do ('Does not start an agent, create a task, or read logs'), implicitly telling the agent when to avoid it. However, it does not explicitly state when to prefer this tool over alternatives like create_task or invoke_discovered_tool, and could offer more direct 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?

No annotations provided, so description fully carries burden. It discloses that safe_fix writes state transitions atomically with backup (status.json.bak), audit fields, and reconcile.log. Also states it never touches tasks owned by an active watcher, and only applies high-confidence fixes.

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?

Description is somewhat long but every sentence provides essential information. Front-loaded with version and core purpose. Could be slightly tightened but no wasted words.

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

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

No output schema, but description indicates return types (diagnosis report, status transitions) adequately. Covers all parameters, side effects, and constraints. Clearly differentiates from many sibling task tools.

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

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

Schema coverage is 100%, but description adds significant meaning: clarifies 'report_only' vs 'safe_fix' behavior, defines 'max_age_minutes' as based on created_at or mtime, and explains 'include_done_candidates' for auditing. This goes well beyond the 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 tool scans stale running/collecting_artifacts tasks and either reports or safely fixes them, using specific verbs and resource. It distinguishes the two modes (report_only vs safe_fix) and mentions constraints like not touching active watcher tasks or low-confidence fixes.

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?

Explicitly explains when to use each mode: report_only for diagnosis without modification, safe_fix for applying high-confidence transitions with backup and atomicity. Also states what it never does (medium/low confidence, active watcher tasks), guiding appropriate use.

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 are provided, so the description must fully disclose behavioral traits. It mentions recording 'rejected_reason' in a file, but omits crucial details like whether the subgoal status changes (e.g., to 'rejected'), if the action is reversible, or any permission requirements.

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 extremely concise—two sentences, front-loaded with the main action and followed by constraints/side effects. Every word adds value without unnecessary elaboration.

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 basic purpose and a constraint (allowed statuses), but lacks important context such as the resulting subgoal state, error handling, or prerequisites (e.g., subgoal existence). Given no output schema, more detail is needed for a mutation 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%, but the schema descriptions are minimal (e.g., 'Goal ID.'). The description does not add meaningful context to the parameters beyond what the schema provides; it only restates that a reason is used.

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 (Reject a subgoal) and the resource (subgoal), and specifies it can be done with a reason. It implicitly distinguishes from the sibling tool 'accept_subgoal' by focusing on rejection.

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 explicit context on when the tool can be used by listing allowed non-terminal statuses (ready/queued/running/done_by_agent/needs_fix), but does not mention when not to use it or suggest alternatives like 'accept_subgoal'.

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 burden. It explains local vs remote behavior (local guarded commands, remote read-only) and explicitly lists actions it does not perform. Missing details on side effects or state changes, but adequate for a check tool.

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

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

Three sentences: version, main action with behavior split, and explicit non-actions. Front-loaded with key info, no redundant 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?

Adequately explains purpose and constraints for a 6-parameter tool with no annotations or output schema. However, does not describe return value or how results are communicated, and lacks differentiation from sibling check_release_gate.

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 has 100% description coverage, so baseline is 3. The description adds no parameter-specific meaning beyond the schema; it does not explain how parameters like target_stage enum values work or how they relate to the release gate.

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?

Clearly states the tool runs a bounded release readiness check, specifying it wraps existing release gate, and explicitly lists what it does not do (publish, push, tag, create GitHub Release). This differentiates it from siblings like release_verify and release_prepare.

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?

Does not explicitly state when to use this tool versus alternatives like check_release_gate or release_verify. While it describes what it does, no guidance on selection or exclusion criteria beyond the listed non-actions.

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, description discloses defaults, scope (low-risk artifacts under repo_path), and audit summary writing. Does not mention permissions or irreversibility, but is transparent for a cleanup tool.

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, compact and informative. Version prefix is minor overhead but not detrimental. Good structure for quick parsing.

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

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

No output schema; description mentions audit summary but not its content. Lacks explicit return value documentation. Adequate for the tool complexity but could be more 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?

Adds value beyond schema: dry_run default true, patterns default to project policy, repo_path context inside workspaceRoot. Schema coverage is 100%, so description enhances understanding.

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?

Description clearly states 'Clean up release artifacts' using specific rules, with a specific verb and resource. It distinguishes from siblings like release_check, release_prepare, release_verify.

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?

Provides context on default dry_run behavior and scope of non-dry-run removal. Lacks explicit when-not-to-use or alternatives but is clear for typical use.

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 bears the transparency burden. It discloses that it returns only command status (no stdout/stderr) and does not publish/push/tag. However, it does not specify behavior upon command failure (e.g., stop or continue) or authentication requirements, leaving some gaps.

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 three sentences, concise and to the point. The front-loading of 'v1.3.0' is slightly noisy but does not detract significantly from clarity. Overall efficient.

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 explains purpose, return type, and exclusions. However, with no output schema, it would benefit from specifying the status return format and more detail on the command guard mechanism. It is adequate but not fully comprehensive.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context about the 'command guard' but the schema already covers parameter defaults and enum values. The description does not significantly enhance understanding of parameters beyond what the schema provides.

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 runs project-policy release preparation commands, subject to the PatchWarden command guard. It explicitly lists what it does not do (publish, push, tag, create release), distinguishing it from siblings like release_check or release_verify.

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 context on when to use (when commands are pre-approved) and what it does not do, guiding the agent away from using it for publishing tasks. However, it does not explicitly name sibling tools for alternatives, but the context is clear enough.

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 burden. It clearly states the tool makes read-only HTTPS requests and does not run local shell commands nor perform publish/push/tag/create operations. This sufficiently discloses its immutable, non-destructive 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 consists of two short, front-loaded sentences with zero wasted words. Every sentence adds unique value—purpose and exclusions.

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 no nested objects, the description covers the core behavior and constraints. It lacks details on return values or error scenarios, but for a read-only verification tool, the provided information is largely 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 coverage is 100%, so each parameter already has a description. The tool description adds no additional parameter-level context beyond what the schema provides, warranting the baseline score of 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 clearly states the tool's purpose: 'Verify npm/GitHub/CI release facts with read-only HTTPS requests.' It also explicitly distinguishes itself from sibling tools by listing actions it does NOT perform (publish, push, tag, create release), making its 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 implies use for verification but does not explicitly state when to use this tool versus alternatives like release_check, release_prepare, or release_cleanup. No direct guidance on when not to use it is 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?

The description adds behavioral details beyond the annotations: the review is policy-bound, the returned review_id must be passed unchanged, and it expires. It does not contradict readOnlyHint=true or destructiveHint=false, as requesting a review is read-only. It does not disclose denial/expiry failure behavior, but the added flow context is meaningful.

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, zero filler: the first states the purpose, the second states the critical usage constraint. Front-loaded and 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?

This is a complex tool (12 params, a nested operations array, no output schema, and no parameter descriptions), but the description only covers the request/expiry flow. It does not explain how to construct the request per operation_type, what the response contains beyond review_id, or failure semantics. Incomplete for reliable 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?

With 12 parameters and 0% schema description coverage, the description should compensate by explaining parameter roles, but it mentions none of them. The only hint is 'the exact Direct operation to be performed,' implying the fields mirror the operation, yet operation_type enum semantics, path vs source_path/target_path, commands vs operations, and expected_sha256 fields remain completely unexplained. This is a substantial 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 opens with 'Request a policy-bound review for the exact Direct operation to be performed' — a specific verb (Request) and a specific resource (policy-bound review) scoped to the Direct operation domain. This clearly distinguishes it from siblings like audit_session, run_direct_verification_bundle, and apply_patch, making its purpose unmistakable.

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 second sentence provides clear usage context: 'In enforce mode, pass the returned review_id unchanged to the matching operation before it expires.' This tells the agent when the returned value is needed and the time constraint. However, it never explicitly states when to choose this tool over alternatives or when not to use it (e.g., non-enforce mode), so it lacks explicit 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?

The description explicitly states that the original task is unchanged, which is a behavioral trait. However, with no annotations provided, it fails to disclose other important behaviors such as whether the new task is automatically queued, authentication requirements, rate limits, or return format.

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

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

The description is two concise sentences with no unnecessary words. It front-loads the core action and includes a clarifying statement about the original task, making it efficient for an agent to parse quickly.

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 is functional. However, it lacks context about when to use it (e.g., for retrying failed tasks) and does not mention prerequisites like the existence of the original task, leaving some 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?

The schema covers the single parameter (task_id) with a description. The tool description adds value by explaining that the task_id identifies an existing task whose properties are copied, but it does not provide additional details beyond what the schema offers, so baseline 3 is appropriate.

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 creates a new task by copying properties (plan, agent, repo_path, test_command) from an existing task. The verb 'Create' and resource 'new task' are specific, and it distinguishes from sibling creation tools like 'create_task' which likely require full specification.

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 does not provide any guidance on when to use this tool versus alternatives such as 'create_task' or 'create_subgoal_task'. It only describes what it does, leaving an agent without context for decision-making in workflows.

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 indicate destructive behavior, and the description adds that commands run sequentially and that logs are omitted. However, it does not disclose potential side effects of the commands, failure behavior, or what 'bounded structured status' entails beyond the structured annotation.

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

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

The description is a clear, two-sentence summary that is front-loaded with the core purpose and omits unnecessary details. 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?

Without an output schema, the description's term 'bounded structured status' is vague and leaves return format unclear. It also does not explain the interaction with the Direct session, partial execution, or timeout behavior, so the description is incomplete for a destructive 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 75%, and the description adds no additional parameter semantics. It fails to clarify the undocumented timeout_seconds parameter or the exact conditions for review_id, leaving potential ambiguity.

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 runs multiple allowlisted Direct verification commands sequentially and returns only bounded structured status, explicitly noting it omits stdout/stderr tails and log content. This distinguishes it from similar tools like run_verification or get_test_log.

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 a use case (running a bundle of verification commands in a Direct session) but does not provide explicit when-to-use vs. when-not-to-use guidance or name alternative tools. The omission of log content hints at when not to use, but lacks direct 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?

The description details the composition of subtools, immediate return, background execution, and safety boundaries (watcher, allow-list, confinement, confirmation). With no annotations, this provides adequate transparency, though it could mention side effects like task creation explicitly.

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 concise (3 sentences) and front-loaded with the main action, covering the essential flow and constraints 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?

Given the tool's complexity (21 parameters, orchestration of multiple subtools), the description provides sufficient high-level context. The schema handles parameter details, and the description clarifies the return values and follow-up steps.

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 covers 100% of parameters with descriptions, so the tool description adds minimal additional value. It does not elaborate on parameter usage beyond what the schema provides.

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 starts a guarded PatchWarden task loop by composing multiple subtools, distinguishing it from individual tools like create_task or wait_for_task.

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 explains the default behavior (returns immediately, loop continues in background) and advises subsequent calls (wait_for_task, get_task_lineage). However, it does not explicitly contrast with siblings or specify when to use this orchestrated loop versus individual steps.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true. The description adds the allowlist constraint but does not disclose potential destructive side effects or return behavior. The 'verification' label could be misleading given destructiveHint=true, but it does not directly contradict 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?

Two concise sentences, front-loaded with the action and constraint. No redundant phrasing.

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 what the tool returns (e.g., output, exit code) and the significance of the timeout parameter. It only mentions the allowlist and session, leaving the agent to guess about result handling.

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 covers 75% of parameters with descriptions. The tool description does not add extra meaning beyond mapping command to 'whitelisted verification command'. It does not explain review_id or timeout_seconds 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 clearly states the tool runs a verification command, specifies the whitelist constraint, and ties it to a Direct session. This distinguishes it from sibling tools like run_direct_verification_bundle.

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 vs alternatives. It does not mention when not to use it or point to sibling tools like safe_* versions. The only context is 'within a Direct session' which is a prerequisite, not a selection criterion.

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 provided, and the description only mentions returning bounded structured evidence. It does not disclose behavioral traits like whether the operation is read-only, destructive, or what happens to the audit state, leaving significant gaps.

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?