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

Without annotations, the description bears full responsibility. It discloses the verdict logic (Blocker/Unjustified Major to REJECTED), the weighted rubric scorecard when scores are present, and the `arbitration_needed` flag. It does not cover side effects, authorization, or rate limits, but given the absence of annotations, the level of behavioral detail is strong.

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 well-structured and front-loaded with the main purpose. Each sentence adds distinct value (logic, optional parameters, output fields). Slightly verbose but not wasteful; good conciseness for the complexity.

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 nested objects and no output schema. The description covers core verdict rules, optional parameters, and key outputs (`arbitration_needed`, `severity_counts`, `agents_involved`, rubric scorecard). It does not explain the `threshold` parameter or how `weights` map to scores, but references an external rule document and sibling `score_rubric` for additional context. Overall adequate for 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?

Schema description coverage is 0%, so the description must compensate. It explains the `reports` parameter implicitly and details the `min_score` behavior. However, it does not explain `weights` or `threshold`, leaving gaps. The mention of per-dimension scores and weighted rubric adds value beyond the raw 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 verb 'Aggregate and emit' and the resource 'advisory reports', and specifies the verdict logic. While it does not explicitly differentiate from sibling tools, the unique rule-based aggregation behavior is evident.

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 optional `min_score` parameter and its use case for quality bars, and mentions `arbitration_needed` to signal when consolidation is unnecessary. However, it does not provide explicit guidance on when to avoid this tool or suggest alternatives among siblings.

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 confidence levels and heuristic nature, plus suggestion guidance. Without annotations, description adds needed behavioral context beyond 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?

Two sentences pack all essential information: operation, input, output, and usage guidance. 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?

Covers input, output (with confidence levels), and behavior. No missing elements for a simple classification 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?

Adds meaning by clarifying that 'files' refers to changed file paths and that both prompt and files are used for classification. However, no detailed format or constraints 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?

Clearly states the tool performs heuristic classification of WorkType from user prompt and changed file paths. Distinguishes from sibling tools by its specific function.

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 use as a suggestion with 'Treat as suggestion; allow override' but does not explicitly state when to use vs alternatives or provide exclusion criteria.

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

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

With no annotations provided, the description must cover behavioral traits. It discloses the sequence of sub-workflows and that the output is union-ready for dispatch. But it omits details on side effects, authorization needs, idempotency, or error handling – important for a composite 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 concise at two sentences and front-loaded with the main purpose. However, it omits parameter explanations, which are necessary for completeness, slightly reducing conciseness 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 the tool's complexity (15 parameters, nested objects, 3 required), no output schema, and no parameter descriptions, the description is incomplete. It does not provide enough context for an agent to use the tool correctly without referring to sub-tool definitions.

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

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

Schema description coverage is 0% and the description does not explain any of the 15 parameters. It fails to add meaning beyond the raw schema, which is inadequate given the high parameter count and nested structure. The description must compensate but does not.

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

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

The description clearly states the tool is an end-to-end advisory dispatch bundle that orchestrates three specific sub-workflows (compose_squad_workflow, slice_files_for_agent, validate_plan_text) in sequence and returns the union output for parallel dispatch. This specific verb+resource+process distinguishes it from sibling tools that are its individual components.

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 should be used when the full advisory dispatch pipeline is needed, as it bundles the sub-steps. However, it does not explicitly state when to prefer this over calling the sub-tools individually, leaving room for uncertainty.

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 full burden. It discloses that the tool does not call any LLM ('Pure-MCP'), that it builds a prompt and JSON schema, and includes existing tasks. It does not describe any side effects like file modifications or network calls, which is fine for a tool that only generates a prompt. However, it could be more explicit about whether it modifies any state.

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

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

The description is extremely concise—only three sentences—yet conveys all essential information about purpose, non-LLM nature, workflow, and deduplication feature. Every sentence adds value, 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 complexity (4 parameters, no annotations, no output schema), the description lacks parameter explanations. It does well to explain the workflow and deduplication, but without parameter semantics, the agent may struggle to invoke it correctly. The description is incomplete for a tool with this many inputs.

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

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

Schema description coverage is 0% and the description does not explain any of the 4 parameters (workspace_root, prd_text, max_tasks, include_existing). The description provides context about the workflow but gives no details about what each parameter means or how they affect output. This is a significant 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 clearly states the tool builds a prompt + JSON schema for decomposing a PRD into atomic tasks. It explicitly distinguishes itself from calling an LLM ('Pure-MCP: does NOT call any LLM') and differentiates from the sibling tool 'record_tasks' by describing the workflow where the host uses this tool's output then calls record_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 guidance on when to use the tool: to decompose a PRD. It explains the workflow (caller feeds prompt to its LLM, then calls record_tasks). While it doesn't explicitly state when not to use it, the context is sufficient. The mention of 'includes existing tasks' prevents duplication, which is a usage hint.

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 carries full burden. It discloses that the pipeline is deterministic and describes output components (config, skipped_paths, disabled_agents). However, it does not state whether the tool modifies any state (read-only vs. write), which is important for safe invocation.

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 paragraph that front-loads the pipeline steps. It efficiently packs information without wasted words, though breaking into bullet points could improve readability.

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 11 parameters (2 required) with 0% schema coverage, nested objects, and no output schema, the description partially compensates by explaining the pipeline output layout. However, it lacks detailed descriptions for most input parameters and does not fully specify return value structure.

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%. The description only mentions override parameters (force_work_type, force_agents, risk_signals) but fails to explain the other 8 parameters (e.g., workspace_root, user_prompt, base_ref, staged_only). This leaves the agent with limited guidance for correctly filling required fields.

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

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

The description clearly states it is an 'end-to-end deterministic pipeline' listing specific steps (detect_changed_files -> ... -> select_squad). It differentiates from sibling tools (the individual steps) by being the composite workflow that returns the union output.

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 indicates when to use overrides (force_agents, risk_signals, force_work_type) and explains priority (force_agents wins over config.disable_agents). It does not explicitly contrast with sibling step tools, but the composite nature is clear from the pipeline description.

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

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

With no annotations provided, the description discloses key behavioral traits: the use of git diff, default ref range, constraints on refs (allowlist rules, 200 chars), timeout (10s), and output cap (1MB). This gives an agent sufficient understanding of the tool's behavior beyond just 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 highly concise with three sentences. It front-loads the main purpose and efficiently provides usage details and constraints without 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?

Given there is no output schema, the description could be more complete by explaining the return format (e.g., list of filenames with status codes). However, it does mention 'detect changed files' and the output cap, leaving some ambiguity but still functional. Additional detail on output would improve completeness.

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

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

Schema description coverage is 0%, so the description must add meaning. It explains the use of base_ref and staged_only, but does not cover working_tree or with_stats. workspace_root is required but not described. The description adds partial value, compensating somewhat for the lack of schema descriptions.

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

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

The description clearly states the tool detects changed files in a git workspace using 'git diff --name-status'. It is a specific verb-resource combination that distinguishes this tool from siblings, which are unrelated to git diff.

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

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

The description explains the default behavior (HEAD~1..HEAD) and how to customize using base_ref or staged_only. While it doesn't explicitly state when not to use the tool, it provides clear context and constraints (allowlisted refs, timeout, output cap), guiding 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?

Fully discloses side effects (atomically claims and clears the staging file), no-op behavior, and return values (deduplicated file paths and breadcrumb count). Since no annotations exist, the description compensates completely.

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

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

Four sentences, front-loaded with main action. The last sentence about the squad skill context adds helpful usage detail without being overly 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?

Explains return values and side effects adequately. With no output schema, it covers essentials. Could be more precise about data types (e.g., list vs. set), but sufficient for most agents.

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 only parameter `workspace_root` lacks schema description (0% coverage) and the tool description does not explain its purpose or expected format beyond the parameter name. This leaves 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 action ('drain') and specific resource (`.squad/pending-journal.jsonl`), and distinguishes it from sibling tools like `record_run` by noting its role in Phase 10 before `record_run`.

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 explicit usage context: called once in Phase 10 before `record_run`, and mentions the no-op condition when journaling is not `opt-in`. However, it does not explicitly state when not to use or offer 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?

Discloses side-effecting atomic write, sequential ID allocation. Without annotations, description provides key behavioral context.

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-sentence description with no wasted words. Purpose, behavior, and ID allocation are concisely stated.

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, so description should hint at return value. It only says 'atomic write' but not what is returned. Parameter details are 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 parameters have 0% description coverage and description does not explain workspace_root or task_id meaning. Only 'subtask inputs' is vaguely referenced.

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 'Append subtasks to an existing task' with specific verb and resource. Distinct from sibling tools like 'update_task_status' or 'next_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?

Implies usage when caller has subtask inputs ready, but no explicit when-not-to-use or alternative tools mentioned.

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 reveals the resolution order (local override first, then embedded default), which is helpful behavioral context. However, without annotations, it does not explicitly state that the operation is read-only or describe error handling (e.g., what happens if neither source 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 extremely concise: two sentences with no wasted words. It immediately states the action and the resolution logic, which is well-structured and easy to parse.

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 adequate but lacks details on edge cases (e.g., missing agent or fallback behavior). In the context of many sibling tools, it might benefit from more specificity about the 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?

The input schema has a single enum parameter 'name' with no description, and the tool description adds no additional meaning beyond 'a given agent.' With 0% schema description coverage, more parameter context is expected but not 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 clearly states the tool returns the full markdown system prompt for a given agent and specifies the resolution order (local override → embedded default). However, it does not differentiate from sibling tools like 'list_agents' or 'read_squad_config', which could be confused but are distinct in 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 no guidance on when to use this tool versus alternatives, nor does it mention any context or prerequisites. For example, it doesn't specify that this tool is for retrieving prompt definitions or contrast it with similar tools.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool copies defaults to a specific directory and notes that locally edited files override bundled versions. However, it does not specify behavior regarding existing files, whether the directory is created if missing, or any side effects. The 'force' parameter hints at overwrite behavior but is not described.

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

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

The description is a single sentence that conveys the core functionality without unnecessary words. It includes technical details like environment variables, which adds specificity. Slightly longer than necessary but 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?

For a simple tool with one parameter and no output schema, the description misses key details: it does not explain the 'force' parameter, the return value or success indicator, or prerequisites (e.g., whether the directory must exist). The agent has insufficient information to call the tool correctly in all scenarios.

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 'force' (boolean) is not mentioned in the description, and the schema provides no description. With 0% schema description coverage, the description fails to add any meaning beyond the type. The agent cannot know what 'force' does without additional 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 action: copying embedded agent defaults to a local override directory. It specifies the verb 'Copy', the resource 'embedded agent defaults', and the destination with environment variable or default path. This distinguishes it from sibling tools which handle other configuration or task management operations.

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 should be used to set up local overrides, but it does not explicitly state when to use it versus alternatives, nor does it mention prerequisites or the fact that it should be run before other tools. The guidance is minimal and relies on inference.

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

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

With no annotations, the description carries the full burden. It discloses that the tool returns agent roles, ownership, and naming conventions, implying a read-only operation. However, it does not explicitly state side effects, authorization requirements, or any other behavioral traits beyond the output content.

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

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

The description is a single sentence that is front-loaded with the action and resource ('List all configured agents'). It is concise with no superfluous 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 has no parameters and no output schema, the description provides a basic understanding of what is listed. However, it lacks details on output structure (e.g., field names, types), potential pagination, or system scope (e.g., workspace vs global). It is minimally complete for a simple list tool but could be improved.

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 schema coverage is 100%. The description adds value beyond the empty schema by specifying what information the list will include (roles, ownership, naming conventions), which helps the user understand the output.

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 all configured agents and specifies the attributes returned (roles, ownership, naming conventions). This differentiates it from sibling tools like 'get_agent_definition' (single agent) and 'list_runs' (different entity).

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

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

The description implies usage when a need to see all agents and their key attributes, but does not explicitly state when not to use it or mention alternatives (e.g., 'get_agent_definition' for detailed info on a single agent). No exclusionary 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?

With no annotations, the description fully discloses behavior: it is read-only, folds row pairs, applies filters, returns list or aggregate, and handles missing journal gracefully. This is comprehensive and leaves no ambiguity about 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?

Three sentences, front-loaded with the core identity, then detailed behavior, then edge-case handling. Every sentence adds necessary information 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 10 parameters and no output schema, the description covers almost all relevant aspects: purpose, filters, output modes, and error handling. It lacks explicit description of the return format for the non-aggregate case, but the mention of 'folded list' gives a reasonable hint. Overall, it is sufficient for an AI agent to understand and invoke 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 0%, so the description must explain parameters. It lists filter parameters (since, limit, agent, verdict, mode, invocation, work_type) and mentions aggregate and trend_days implicitly via 'aggregate bundle' and 'trend sparkline buckets'. It also clarifies default aggregate=false. However, it does not detail workspace_root or the exact format of parameters like since (but schema has enums for some).

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 is a read tool for `.squad/runs.jsonl`, describes the two-phase folding, and specifies the two output modes (list vs aggregate). The verb 'Read' and resource 'squad/runs.jsonl' provide a specific and distinct 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 explains that the tool reads runs with filters and can return aggregates. It also notes that missing journal returns empty, not error, which guides usage expectations. However, it does not explicitly differentiate from sibling tools like list_tasks or record_run, which are other read/write tools for different resources.

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 discloses tool reads from a specific file and returns filtered tasks with count, which implies read-only behavior. However, it does not explicitly state it is read-only or discuss authorization, rate limits, 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 conveys purpose, filters, and return value efficiently. Front-loaded with main action. Could be split for readability, 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?

Given 5 parameters (1 required) and no output schema, description covers basic return (filtered tasks + count) but lacks details on task structure, pagination, error handling, or explanation of workspace_root. 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 0% (no parameter descriptions). Description adds meaning for status (filters), agent, changed_files (glob match against task.scope), and limit. However, workspace_root is not explained. Description partially compensates for missing 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?

Description clearly states 'List tasks from `.squad/tasks.json`' indicating verb and resource. It specifies optional filters and return value (filtered tasks + count). This distinguishes it from sibling tools like update_task_status or expand_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?

Description mentions optional filters but does not provide explicit guidance on when to use this tool vs alternatives like update_task_status or expand_task. No when-not-to-use or alternative 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 provided, the description fully covers behavioral traits: it describes the selection logic, the default candidate status, the tiebreaker rule, and the edge case of returning null with a reason and a blocked list. This is comprehensive for an AI agent to understand the tool's behavior.

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

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

The description is two sentences long, with key information front-loaded: the purpose and then details. Every sentence adds value without redundancy. This is an excellent example of conciseness.

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 5 parameters, 0% schema description coverage, and no output schema or annotations, the description is quite complete. It explains the core logic, tiebreaker, and error handling. It could be improved by describing the return object structure more explicitly, but it still provides sufficient context for an AI 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 description adds meaning beyond the input schema for three parameters: candidate_statuses (default pending), agent (optional filter), and changed_files (optional filter). It mentions 'dependencies done' which is not an explicit parameter but is implied behavior. However, it does not explain workspace_root (required) or done_statuses, and schema coverage is 0%, so the description only partially compensates.

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: 'Pick the next ready task' with specific criteria (candidate status, dependencies done, optional filter). It differentiates itself from sibling tools by focusing on task scheduling and sequencing, which is distinct from other operations like listing, updating, or classifying 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 on when to use the tool (to get the next ready task) and what to expect (tiebreaker priority then id, returns null with reason). However, it does not explicitly state when not to use it or mention alternatives among the sibling tools, which would improve 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, but description fully discloses archival, promotion, atomic rewrite, and auto-run behavior. 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?

Single efficient paragraph front-loading purpose, then detailing passes, lock, and dry_run. 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?

Covers key behaviors and constraints. Lacks output format details, but acceptable for a maintenance tool with no output schema.

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

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

Schema coverage 0%, but description explains max_age_days, min_recurrence, and dry_run in context. workspace_root not explained but self-evident.

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?

Describes specific lifecycle maintenance for .squad/learnings.jsonl with two clear passes, distinguishing it from reading/recording 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?

Provides usage context: never auto-runs by default, dry_run for inspection. Does not explicitly list alternatives but context is clear.

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

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

Discloses return behavior: 'filtered entries plus a pre-rendered markdown block'. Mentions filters and purpose to reduce repetition. No annotations provided, but description adequately covers read-only nature and output.

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?

Front-loaded with core purpose, then details. Slightly long but every sentence adds value. Could be more concise but 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?

With 8 parameters and no output schema, the description lacks explanation for several parameters and return format details beyond markdown block. Adequate but incomplete.

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

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

Description explains file path overridability and filters (agent, decision, changed_files), but misses details on limit, include_rendered, include_archived, include_summary. Schema coverage is 0%, so description partially compensates.

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 action 'Read' and the resource 'recent team decisions from `.squad/learnings.jsonl`', with path overridability. Distinguishes from siblings like record_learning and prune_learnings.

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?

Specifies usage context: 'Used by the /squad:review skill in Phase 5 (advisory) and Phase 10 (consolidation)'. Provides filter options but no explicit when-not-to-use 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?

Describes return fields (effective weights, threshold, etc.) and that it returns null if no file. No annotations provided, but description provides adequate behavioral info for a read 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?

Single paragraph, front-loaded with action, concise with 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?

Complete for a simple read tool: covers purpose, output, usage context. No missing details given no output schema.

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

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

The one parameter workspace_root is explained in context ('at the given workspace_root'). Though schema coverage is 0%, the description adds sufficient meaning for this simple param.

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 and resolves .squad.yaml at workspace_root. Distinguishes from sibling tools by noting that composers read it automatically.

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 this tool is for explicit introspection and for clients that build their own bundle, contrasting with composers that handle it automatically.

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 side-effects ('writes to disk') and explains the impact on future runs. Since no annotations are provided, the description carries full burden. It lacks details on permissions or error behavior but provides good context for a write operation.

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

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

The description is concise with two sentences, front-loading the main action and including essential context about side-effects and future behavior. 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?

Given 12 parameters and no output schema or annotations, the description is insufficient. It does not explain the parameters or return value, leaving the agent without critical information for correct invocation.

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

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

The description mentions 'team decision (accept | reject)' which maps to the 'decision' parameter, but does not explain any of the other 11 parameters. With 0% schema description coverage, the description fails to compensate for the missing parameter semantics.

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

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

The description clearly states the verb 'append' and the resource '.squad/learnings.jsonl', and specifies the action of recording a team decision (accept/reject). It distinguishes from sibling tools like prune_learnings and read_learnings by focusing on appending a 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 explains the purpose: to prevent re-suggestion by injecting decisions into future prompts. It notes that the caller is responsible for user confirmation, implying appropriate usage. However, it does not explicitly differentiate from alternative sibling tools.

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

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

The description reveals several behavioral traits beyond the input schema, including validation against schema_version:2, size enforcement via MAX_RECORD_BYTES and RECORD_TOO_LARGE, file mode 0o600 on first create, and control character stripping. With no annotations provided, the description carries the full burden and covers important mutation and safety details, though it could mention error handling beyond overflow.

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

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

The description is a single focused paragraph that front-loads the core action. Each sentence provides distinct value: purpose, contract, validation, size limit, caller responsibility, file mode, and string sanitization. It is concise and structured logically, though it could benefit from bullet points for readability.

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 complexity of the tool (nested record object, multiple validations, file operations), the description covers key aspects: action, constraints, single-writer model, and data integrity responsibilities. However, it lacks any mention of return values or success indicators, and no output schema is provided. This gap prevents a perfect score.

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 is extremely rich with many nested properties, so the schema itself explains parameters thoroughly. The description adds context about validation and constraints but does not explain individual parameters like workspace_root or record properties. With 0% schema description coverage, the description should ideally compensate more, but the schema's high detail keeps the baseline at 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 action ('Append one RunRecord'), resource ('RunRecord'), and target file ('.squad/runs.jsonl'), distinguishing it from sibling tools like 'list_runs' (listing) and 'record_learning' (other recording). It leaves no ambiguity about what the tool does.

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

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

The description explicitly defines a 'single-writer contract' and lists the allowed calling skills with phase contexts (e.g., squad Phase 1 + Phase 10). It also alerts the caller to match in_flight↔terminal rows by id. However, it does not explicitly state when not to use this tool compared to other recording tools, missing a full exclusion clause.

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 reveals side-effects (writes to file), atomic write method (tmp+rename), and validation rules (unique ids, dependency resolution, no self-deps). Also notes the host LLM responsibility for user confirmation.

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, each adding critical information. No wasted words. The most important action and resource are 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?

The description covers purpose, parameters, behavior, and validation. However, it omits the return value or success indication, which is relevant since there is no output schema.

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

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

Schema coverage is 0%, so the description compensates well by listing the fields inside the 'tasks' array. However, it does not describe the 'workspace_root' parameter, leaving a minor 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 clearly states the verb 'bulk-create' and the specific resource '.squad/tasks.json'. It lists the fields included in each task, distinguishing it from siblings like 'expand_task' (single task) or 'update_task_status'.

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

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

The description gives a usage context: 'after parsing a PRD' and a requirement to confirm with the user. It implies bulk creation rather than individual tasks, but does not explicitly state when not to use it or list 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?

With no annotations provided, the description must carry the burden of behavioral disclosure. It states 'Pure function' and gives the risk mapping, which is useful. However, it lacks details on error handling, input validation, or how numbers (files_count, loc_changed) are used despite mentioning only boolean signals. The description adds some transparency but is not comprehensive.

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

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

The description is extremely concise: three short sentences, each adding distinct information (purpose, property, mapping). No wasted words, front-loaded with the key 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?

Given the tool has 7 parameters, no output schema, and no annotations, the description is insufficient. It does not explain how the risk score is computed from the parameters, leaving ambiguity (e.g., are boolean signals summed? How are numbers handled?). The agent lacks information to correctly invoke the tool without guessing.

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 7 parameters with 0% description coverage. The description only says 'from boolean signals', but the schema includes both boolean and number parameters. It does not explain how each parameter contributes to the risk score or how the count is computed from mixed types. The mapping given is vague regarding the role of numeric parameters, offering minimal semantic help.

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 'Compute' and the output 'risk level (Low/Medium/High)' from 'boolean signals'. It includes the mapping from score range to level, making the purpose very specific. While it doesn't explicitly differentiate from siblings like classify_work_type, the unique mapping and mention of boolean signals set it apart sufficiently.

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 'Pure function', implying it has no side effects and can be called freely. However, it does not provide explicit guidance on when to use this tool versus similar siblings (e.g., classify_work_type, score_rubric) or any exclusions. Usage context is implied but not fully explicit.

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

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

With no annotations, the description fully discloses behavioral traits: expects scores 0-100, default weights, renormalisation across active agents, returns weighted_score, per-dimension breakdown, pass/fail vs default threshold 75, and ASCII scorecard. 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?

Three sentences: first states core purpose, second adds weight/threshold details, third explains renormalisation and outputs. Every sentence adds value, no redundancy, front-loaded with 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?

Given 3 parameters, no output schema, and nested objects, the description covers inputs (scores, weights, threshold), behavior (weighting, renormalisation), and outputs (weighted_score, breakdown, pass/fail, ASCII card). It handles the partial advisory pass special case, making it complete for an agent selecting this 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?

Despite 0% schema description coverage, the description adds meaning by explaining each dimension corresponds to an agent, scores are 0-100, weights have defaults overridable via .squad.yaml, and threshold defaults to 75. It could detail the weights object structure (only allowed agent names) but provides substantial semantic value beyond the raw 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 computes a weighted multi-dimensional rubric scorecard from per-agent advisory scores, distinguishing it from sibling tools like score_risk by focusing on rubric scoring with multiple dimensions and pass/fail threshold.

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 (computing scorecard from per-agent scores) and explains key features like default weights, overridable weights, and renormalisation. However, it does not explicitly state when not to use or mention alternative tools, though the context is sufficient for most use cases.

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 reading up to 16384 bytes per file when workspace_root is set and ext-gating signals. With no annotations, description provides useful behavioral context beyond basic read traits.

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 purpose, 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?

With 5 parameters, no output schema, and no parameter descriptions, the description omits return values, algorithm details, and parameter semantics, leaving significant gaps 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 description coverage is 0% and description does not explain parameter meanings (e.g., files structure, read_content, force_agents). Only workspace_root and file reading are partially 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?

Clearly states 'Select agents for a work type given changed files', with specific verb and resource. Distinguishes from sibling tools like classify_work_type and slice_files_for_agent.

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 context (changed files, work type) but lacks explicit when-to-use or alternatives. Mentions ext-gating but no 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 must cover behavioral traits. It discloses the read limit (16384 bytes) and that it depends on workspace_root, but lacks information on whether the tool is read-only, what happens to the original files, or any side effects. This is insufficient for a tool that reads file content.

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 core purpose, and contains no fluff. It is concise but could benefit from a clearer separation of behavior and parameters.

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 (filtering with content sniffing) and lack of output schema, the description is incomplete. It does not explain the return value, error conditions, or how the filtering logic works in detail. Significant gaps remain.

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

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

Schema coverage is 0%, so the description must explain parameters. It does not mention the meaning of 'agent', 'files', 'read_content', or 'workspace_root' except a brief note on workspace_root. No parameter-level detail is provided, leaving the agent without guidance on how to use the inputs.

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

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

The description clearly states the verb 'Filter' and the resource 'a file list to those owned by a specific agent'. This distinguishes it from the sibling 'slice_files_for_task' which likely filters by task. The purpose is 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?

The description provides some context on how it works ('Uses path hints + content sniff') but does not explicitly state when to use this tool over its siblings, nor does it mention any exclusions or prerequisites. Usage guidance is implied but not explicit.

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

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

No annotations provided, so description carries full burden. It discloses that matching uses a glob primitive, and without scope all files match. Provides context about the glob being the same as skip_paths and learnings scope. Does not mention error states or side effects, but core behavior is clear.

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-loading the action, no extraneous words. Efficiently communicates the tool's core purpose and a key behavioral 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 simple filter tool with 3 parameters and no output schema, the description explains the filtering logic but omits output format and error handling (e.g., what happens if task_id is invalid or glob malformed). Adequate 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 has 3 parameters with 0% description coverage. The description does not mention any parameter details, leaving the agent to infer from context. Fails to compensate for the schema's lack of 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?

Description clearly states the tool filters a file list based on a task's scope glob. It distinguishes from sibling tools by referencing the same glob primitive as skip_paths and learnings scope, but does not explicitly mention the sibling slice_files_for_agent.

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?

Implied usage: use when needing to filter files by task scope. Explains behavior when no scope exists but lacks explicit when-not or alternative tool 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 the description carries full burden. It explicitly states 'Stamps updated_at', 'Atomic write', and 'Throws when the task / subtask id is unknown', providing clear behavioral context.

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 defines the action and allowed values, second adds behavioral traits. No redundant phrases, 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 4 parameters, no output schema, the description covers the mutation, allowed values, atomicity, timestamp, and error condition. Missing success return behavior, 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 0%, leaving parameter descriptions to the tool text. The description clarifies 'task (or subtask) status' implying task_id and optional subtask_id, and the status enum is listed. However, workspace_root is not explained.

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

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

The description uses specific verb 'Flip' with clear resource 'task (or subtask) status', lists all allowed statuses, and distinguishes itself from sibling tools like 'classify_work_type' or 'next_task' by focusing on direct status mutation.

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. It does not mention when not to use it or suggest other tools for similar purposes.

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. The description discloses it is heuristic and advisory, but lacks details on side effects, performance, or error behavior. With no annotations, the description carries moderate burden and provides some 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 pack the essential purpose and key behavioral note. No superfluous information; efficient 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?

Core functionality is covered, but missing details on return value (no output schema) and parameter format. For a simple tool, this is 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?

Only one parameter 'plan' with no schema description coverage. The description calls it 'plan text' but does not explain format or expected content beyond the rule list. Insufficient guidance for the agent.

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 performs a heuristic check for inviolable rule violations in plan text, listing specific examples like git fences and emojis. It differentiates from sibling tools which handle different workflows.

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?

Declares the check is 'advisory only — never blocking,' which tells when to use it as a non-blocking validation. Does not explicitly compare to alternatives, but the context is implied.

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