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

Annotations already indicate the tool is read-only and idempotent. The description adds value by specifying the types of events included (tasks, decisions, blockers, sessions) and the time range and filtering behavior, though it does not detail output format or potential 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 brief, front-loaded with the core purpose, and every sentence adds value. The bullet-like format for event examples is efficient and easy to scan.

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 clear purpose, the description lacks an overview of the return value (e.g., list of event objects with timestamps) and does not provide enough context for an agent to fully understand the output. With no output schema, more detail is needed.

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% (3 of 4 parameters described in schema). The description summarizes these parameters ('filter by workflow, time range, and event types') but adds no new details beyond what is already in the schema. The 'limit' parameter lacks description in both schema and 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 'Get recent activity events' with specific verb and resource, and lists examples that distinguish it from sibling tools focusing on individual items like tasks or blockers.

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 mentions filtering options but does not explicitly explain when to use this tool versus alternatives (e.g., cph_task_list for specific user tasks). Usage context is implied but not clarified.

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 non-readonly, non-destructive, non-idempotent. Description adds significant context: auto-sets task status to 'blocked' if task_id provided, and emphasizes not recording retroactively. 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?

Description is front-loaded with main action and immediate call-to-action. Bullet list of blocker types is clear, though slightly verbose. Efficient overall.

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, when to use, parameter meanings, and auto-behavior. No output schema, but missing return value explanation is minor omission given creation tool usage pattern.

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 60% schema coverage, description explains meaning of title, blocker types (with examples), task_id auto-behavior, and description purpose. Does not cover workflow_id, but overall adds 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?

Description clearly states it logs a blocker preventing progress, enumerates blocker types, and distinguishes from sibling tools like cph_blocker_list and cph_blocker_resolve.

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 instructs to call immediately when blocked and before asking user or trying workarounds, but does not provide when-not-to-use alternatives beyond that.

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 idempotent and non-destructive. The description adds that escalation marks for urgent attention and surfaces to stakeholders, but doesn't detail any side effects (e.g., notifications, state changes). No contradiction with annotations.

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

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

Two concise sentences with the primary action and usage context front-loaded. No redundant or extraneous text.

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

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

For a simple tool with two required parameters and annotations present, the description covers the essential purpose and usage. It lacks mention of return or confirmation, but given no output schema and low complexity, it is nearly 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 50% with only 'reason' having a description. The tool description does not compensate for the missing 'blocker_id' parameter semantics, leaving the agent to infer its purpose. Baseline 3 adjusted down due to lack of compensation.

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 ('Mark a blocker as escalated') and the resource ('blocker'), with a specific state ('open but needs urgent attention'). It effectively distinguishes from sibling tools like resolve (which closes) and create.

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 a clear usage scenario: 'when a blocker has been open too long and needs to be surfaced to stakeholders.' While it doesn't explicitly mention when not to use or list alternatives, the context is sufficient given the sibling tool names.

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 idempotentHint=true. Description adds the duplication warning about session_init but does not disclose other traits like pagination behavior or required scopes. It adds some value but is 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 sentences, front-loaded with purpose. Every word earns its place. No wasted 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 list tool with 4 optional parameters and no output schema, the description omits pagination details (limit/offset) and response format. Adequate but missing information that would help the agent use the tool fully.

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%; description only vaguely mentions 'by workflow and/or status' without detailing parameters like workflow_id (uuid), status (enum with default), limit, or offset. It does not meaningfully compensate for the lack of schema descriptions.

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

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

Description clearly states 'List blockers by workflow and/or status' with a specific verb and resource. It distinguishes from sibling tools like cph_blocker_create and cph_session_init by noting that session_init already surfaces open blockers.

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 'Call this when user asks about blockers' and warns 'session_init already surfaces open blockers — don't duplicate', providing clear when-to-use and 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?

The description adds significant context beyond annotations. It explains the auto-behavior (task reset to in_progress) and the importance of the resolution note as training data. Annotations mark it as idempotent, which is consistent.

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 and a separate line for auto-behavior. It front-loads the core purpose and then adds critical context without 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?

For a 3-parameter tool without output schema, the description covers the action, parameter importance, and side effects. It could mention error cases (e.g., nonexistent blocker) but is sufficient for typical use.

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 67% of parameters with descriptions. The description reinforces the resolution parameter's importance and connectivity to training, adding value over the schema alone. For blocker_id, no extra info is 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 starts with 'Mark a blocker as resolved,' which is a specific verb+resource combination. It clearly distinguishes from sibling tools by not creating, escalating, or listing blockers.

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 (when a blocker is resolved) and emphasizes providing a resolution note, but it does not explicitly state when not to use it or compare with alternatives like cph_blocker_create or cph_blocker_escalate.

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 provide idempotentHint=true and destructiveHint=false. The description reinforces this with 'Upserts' and 'safe to call multiple times', and adds usage context. It does not contradict annotations. However, it omits details like return value or side effects, but the idempotency hint reduces the need for that.

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 short paragraphs, front-loading the key action. It could be slightly more streamlined (e.g., merging the first two sentences), but it remains focused and avoids 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 simplicity (no output schema, 2 required params), the description adequately covers what, when, and how to use it. It explains the upsert behavior and the structure of areas, making it complete enough for an agent to invoke correctly. A minor gap is lack of mention of response, but not critical.

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 at the top level, the description compensates by explaining the areas parameter structure with an example ('src/auth/**') and clarifying that responsibility and dependencies are optional. It also explains the role of workflow_id via 'Upserts by workflow_id + path_pattern'. This adds meaningful context beyond the schema's minimal 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 registers or updates file area ownership for a workflow, with a specific verb 'register or update' and resource 'file area ownership'. It distinguishes from sibling tools by focusing on codebase indexing for workflows and explicitly mentions 'plan mode', which is unique among the provided sibling 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?

Explicitly says 'Use this during plan mode' and 'safe to call multiple times', providing clear context. However, it does not contrast with alternative tools like cph_context_sync, which might also deal with codebase context, so some ambiguity remains.

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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: first call returns full snapshot, subsequent calls return deltas within token budget, and conflict recovery 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 concise and well-organized: a single-line purpose, then bulleted usage instructions, then parameter list. It avoids redundancy, though the parameter list repeats schema info.

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 4 parameters and no output schema, the description covers usage timing, behavioral modes (full vs delta), and error recovery. It lacks return format details but annotations and description provide sufficient context for an agent.

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

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

Schema has 75% coverage with parameter descriptions. The description adds extra meaning like workflow_id from CLAUDE.md and cwd for git context. However, some parameters like depth only have enum values, and the description does not elaborate further.

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 synchronizes project context with the database, using specific verbs and resources. It distinguishes from siblings like 'cph_session_init' by explaining its delta-based update behavior and conflict recovery role.

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

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

Explicitly instructs to call at start of every session and after each task, and to use on conflict errors. However, it does not explicitly state when not to use or provide alternatives, though siblings suggest other 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 discloses that it attaches commit_hash and diff_stat to decisions recorded in the last 30 minutes without an existing commit. Annotations include idempotentHint, and the description aligns with that. It doesn't detail error conditions but is transparent about its internal nature.

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 clear sentences, front-loading the purpose and restriction. No unnecessary words or repetition.

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 is internal and has no output schema, the description sufficiently explains its effect and constraints (30-minute window, idempotency). It could mention what happens if workflow_id is invalid, but overall is complete for its context.

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 only 33% (diff_stat has a description). The tool description mentions attaching commit_hash and diff_stat but doesn't explain workflow_id. The schema provides types and required status, so the baseline is adequate but the description adds minimal value 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 link recent decisions to a commit, called by a post-commit git hook. The verb 'attach' and resource 'commit' are specific, and it differentiates itself from sibling tools like cph_decision_record.

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 instructs not to call manually and states the hook calls it automatically after every commit. This provides clear when-not-to-use guidance, though alternative manual methods are not 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?

Annotations already indicate read-only and idempotent behavior. The description adds that it returns 'rationale and alternatives', which is useful but does not detail response structure or error behavior, which is relevant given no output 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 concise sentences, front-loaded with purpose. No redundant or missing 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 get tool with comprehensive annotations, the description adds the return content and usage trigger. It lacks mention of error cases or response format, but given the tool's simplicity, it is largely 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 0%, so the description should compensate. It does not explicitly describe the decision_id parameter, but the context of using it after search implies its purpose. This partial compensation yields a 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 explicitly states the verb 'Get' and the resource 'single decision', and specifies the content includes 'rationale and alternatives', clearly distinguishing it from sibling tools like list or search.

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

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

It directly advises to use after cph_decision_search returns IDs, providing clear context. However, it does not explicitly list when not to use or mention alternative 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it returns only a summary view, which is behavioral context beyond the annotations. It does not mention pagination or rate limits, but the safety profile is well-covered by 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 that front-load the purpose and then provide usage guidance. No unnecessary words, 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?

While the description gives clear usage context, it omits details about pagination (limit/offset), the meaning of 'summary view', and the required workflow_id. Given the lack of output schema and low schema coverage, the description should provide more parameter and return information.

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 only 25% (only the tag parameter has a description). The tool description does not add any parameter documentation, failing to compensate for the low coverage. The purpose of limit, offset, and the format of workflow_id are 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 clearly states the tool lists decisions for a workflow, with a specific verb and resource. It distinguishes from siblings by noting that session_init handles automatic surfacing, and there are separate tools for getting a single decision (cph_decision_get) and searching (cph_decision_search).

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

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

The description explicitly states when to call this tool: when the user explicitly asks to see decisions. It also directs agents away from this tool when session_init is appropriate, which surfaces relevant decisions automatically. This provides clear alternatives and 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?

Annotations indicate readOnlyHint=false and destructiveHint=false. Description explains it records decisions and mentions the post-commit hook, but does not disclose potential side effects (e.g., triggering notifications). Behavior is straightforward for a recording 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 somewhat lengthy with a detailed parameter list that partially repeats schema info. The usage guidelines are front-loaded, but the parameter section could be more concise.

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 17 parameters and no output schema, the description covers purpose, usage scenarios, parameter semantics, and a behavioral note about commit hashes. It is fairly complete for successful invocation.

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

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

Schema coverage is 65%. Description adds meaning to parameters like 'context' (problem and constraints), 'rationale' (why this option), and 'alternatives_considered' (structured list). Enums for reversibility and confidence are described.

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: 'Record an architectural, design, or process decision.' It distinguishes itself from sibling tools like cph_decision_get, cph_decision_list, and cph_decision_search by focusing on recording new decisions.

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 scenarios for when to record a decision (e.g., 'chose between two or more approaches', 'made an assumption about requirements', 'the word "because" appears'). It does not explicitly state when not to use, but the positive guidance 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?

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so agent knows it's safe and idempotent. Description adds useful behavioral details: returns summary view (id+title+decision only) to preserve context budget, which goes beyond annotations. No contradiction.

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

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

Three concise sentences front-loaded with purpose, then usage, then return format. Every sentence adds value with no redundancy or 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 straightforward search functionality, three parameters, and no output schema, the description fully covers: input (keyword search across fields), output (summary view), use case (anti-repetition), and link to sibling for details. 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?

Schema description coverage is 67% with meaningful descriptions for query and workflow_id. Description adds minimal extra semantics beyond 'search by keyword' and the fields. Does not elaborate on limit's purpose or constraints beyond schema's min/max/default. Adequate but not exceptional.

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 'search' and resource 'decisions', and specifies the fields searched (title, decision, context, rationale). Clearly differentiates from siblings like cph_decision_get (full details) and cph_decision_list (list all).

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: 'CALL THIS before making any significant architectural choice to check if it was already decided.' Brands it as 'primary anti-repetition tool.' Also clarifies when to use the sibling cph_decision_get for full details.

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 safe read operations. Description adds that it uses git context from the current branch and may suggest creating a workflow, providing useful behavioral context beyond 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?

Three short sentences: main purpose, usage conditions, and return info. 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?

Covers essential aspects for a simple read tool: when to use and return type. Lacks explicit statement that it reads the current git branch automatically, but implied.

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 the only parameter 'cwd' with description; main description does not add further explanation, meeting baseline for 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?

Clear verb 'detect' and resource 'workflow from git context'. Distinguishes from sibling tools like cph_workflow_list by specifying git-branch-based detection.

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 call: no workflow_id in CLAUDE.md or on unfamiliar branch, and mentions return values (match or suggestion).

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 declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds behavioral context: it is the only proactive call, returns specific context fields, and includes a hint. No contradiction.

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

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

Well-structured with bold call-to-action, explanation, then args list. Slightly verbose but each sentence adds value. Could be trimmed slightly 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?

Describes return type (SessionContext with fields) and depth behavior. Lacks error handling or invalid workflow_id scenarios, but given the tool's simplicity and no output schema, it is largely 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?

Description elaborates on each parameter beyond schema: workflow_id source (CLAUDE.md), cwd purpose (current working directory), depth levels with token estimates and content breakdown. Adds significant 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 explicitly states it should be called first at the start of every session and explains it returns orientation context (active tasks, open blockers, decisions). It distinguishes itself from siblings by noting it is the only proactive tool and lists tools not to call afterward.

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?

Clear when to use (first thing in session) and what not to use afterward (workflow_summary, task_list, decision_list). Provides depth parameter guidance and advises pulling individual records on demand.

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

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

Annotations include idempotentHint=true, and the description aligns perfectly by noting the setting is saved and auto-applied, implying idempotency and no side effects. It adds value by clarifying that the preference is persistent and linked to git email, which is beyond what annotations provide.

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: four sentences total, with the first sentence stating purpose, the next explaining persistence, and the last three defining options. Every sentence is valuable 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 simple preference-setting tool with no output schema, the description covers all necessary context: what it does, how it persists, how to use the depth levels, and parameter details. It is complete for the task.

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 50% coverage (engineer_id has description, depth does not), but the description compensates fully by explaining the three enum values ('minimal', 'standard', 'deep') with detailed contexts. This adds significant meaning 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: 'Set your personal retrieval depth preference for session init.' This is a specific verb-resource combination that distinctly identifies what the tool does, and it differentiates from siblings which are about tasks, blockers, workflows, etc.

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 persistence ('saved by your git email and applied automatically on every future session') and defines the three depth levels with practical guidance. However, it does not explicitly state when to use this tool versus alternatives or when not to use it, which would elevate the score to 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?

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context about the return values (storage summary and active workflow count), which goes beyond annotations but does not describe any additional behavioral 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?

The description is two sentences with no wasted words. The first sentence states purpose, the second gives usage guidance. It is front-loaded and concise.

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 is complete: it explains the purpose, return values, and usage context. There are 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 input schema has no parameters, so schema coverage is 100%. The description does not need to add parameter semantics. It implies the tool takes no input, which is correct.

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 'Get' and the resource 'Claude Project History status' and specifies the output as 'storage summary and active workflow count'. It distinguishes from sibling tools by explicitly stating it is not for project context and points to cph_session_init for that.

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 to use ('check that the plugin is working') and when not to use ('not to get project context') along with the alternative tool (cph_session_init).

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 state transition behavior, which adds context beyond annotations. Annotations provide idempotentHint=true, and the description confirms the effect (cancelling). No contradiction. However, it does not detail side effects like what happens to dependent tasks.

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, using a state machine notation and two bullet points. Every sentence adds value, and the structure is front-loaded with the main action.

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 cancellation tool with moderate complexity, the description covers the state machine and parameter recommendations. It does not include return values or error handling, but the absence of an output schema and the idempotent hint mitigate this 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 50% (task_id lacks description). The description adds 'The task to cancel' for task_id and 'optional but recommended' for reason, which provides meaningful guidance beyond the schema's label for reason.

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 the verb 'Cancel' and resource 'task' clearly. The state machine transitions (pending|in_progress|blocked -> cancelled) further clarify the scope, distinguishing it from sibling tools like cph_task_create or cph_task_start.

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

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

The description implies use when a task is 'no longer needed' and the state machine shows valid starting states, but it does not explicitly state when not to use the tool or compare with alternatives (e.g., cph_task_update). Guidance is present but not exhaustive.

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?

Adds state machine behavior and emphasizes criticality of actual_minutes for estimation training, going beyond annotations that indicate idempotentHint=true with no contradiction.

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

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

Concise with front-loaded purpose and state machine; each sentence adds value, though actual_minutes explanation could be slightly trimmed without losing meaning.

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

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

Adequately covers inputs and state, but lacks return value description; no output schema, so a brief note on what the tool returns 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?

With only 33% schema description coverage, the description provides rich meaning for all three parameters: explains task_id, elaborates actual_minutes with ground truth context, and clarifies completion_notes as optional gotchas.

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 'Mark a task as completed' and details the state machine transition from in_progress to completed, distinguishing it from siblings like cph_task_cancel and cph_task_start.

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

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

Explicitly states when to use (task in_progress) and when not (rejects otherwise), but does not mention alternative tools for other states.

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 are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden. It clearly states the creation action, the requirement to call start after, and the consequence of skipping estimated_minutes (exclusion from estimation analysis). This adds behavioral context beyond annotations. It does not discuss potential failures or side effects, but is sufficient.

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 with a brief intro, usage guideline, arguments list, and return info. It front-loads the key usage instruction. While the 'Args:' section repeats parameter names, it is not overly verbose. It efficiently conveys essential information without wasted sentences.

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 absence of an output schema, the description mentions 'Returns: Created task', which is adequate. It covers all 6 parameters, usage timing, and next steps (call start). It could be enhanced by mentioning error conditions or required permissions, but for a creation tool with clear guidance, it is sufficiently 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 only 17% (only estimated_minutes has a description). The tool description adds meaningful semantic context for all 6 parameters: explains workflow_id ('Which workflow'), title ('What you're doing'), priority enum values, estimated_minutes importance with explicit advice to guess if unsure, and optional nature of description and parent_task_id. This compensates fully for the sparse 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 explicitly states 'Create a task within a workflow' with a clear verb and resource. It provides context for when to call it ('beginning any discrete piece of work that will take more than ~5 minutes'), which helps distinguish from other task-related tools like cph_task_start or cph_task_update, though it does not explicitly compare.

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

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

The description gives explicit when-to-use ('beginning any discrete piece of work... >5 minutes') and when-not-to ('Create BEFORE starting work, not after'). It also directs the agent to call cph_task_start immediately after, providing clear sequential guidance. Sibling tools like cph_task_start are implicitly referenced, offering excellent usage 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?

Annotations already indicate read-only and non-destructive behavior; the description adds that it includes subtasks and blockers, but does not discuss error handling or response 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 a single, clear sentence with no unnecessary words, effectively front-loading the 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 retrieval tool with one required parameter, the description is mostly complete, though it lacks mention of error conditions such as missing or invalid task IDs.

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

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

Schema description coverage is 0%, and the description does not explain the 'task_id' parameter at all, leaving the agent without guidance on what value to provide.

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

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

The description clearly states a specific verb ('Get') and resource ('task'), and distinguishes from sibling tools like cph_task_list by specifying it returns full details including subtasks and open blockers.

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 cph_task_list or cph_task_create; the usage is implied by the name but not explicitly stated.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds useful context: returns minimal fields for efficiency, and that session_init provides active tasks. 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 short paragraphs, each sentence adds value. First sentence states purpose, second contrasts with sibling, third gives usage constraint. No 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?

No output schema, but description specifies return fields. Lacks explanation of pagination parameters (limit, offset) and include_subtasks. For a list tool with 5 parameters and no output schema, it is nearly complete but missing some param details.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only mentions filtering by workflow and/or status, ignoring include_subtasks, limit, and offset. This is insufficient for an agent to understand all 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 'List tasks filtered by workflow and/or status' with specific verb and resource. It distinguishes from sibling cph_task_get by noting this returns only ID and title for efficiency, while cph_task_get provides full details.

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 'Call this only when explicitly asked' and notes that session_init already provides active tasks, so this tool is redundant unless specifically requested. Also names alternative for full details.

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

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

Beyond annotations (which show idempotentHint=true), the description adds behavioral context: it records start time, transitions state, and enables file writes via the hook system. No contradiction with annotations.

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

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

Three short sentences with zero wasted words. Action verb and resource are front-loaded. Every sentence adds 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?

Given the annotations, sibling tools, and single parameter, the description fully explains when to use, what it does, and behavioral consequences. No output schema needed as return is likely a simple success indicator.

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 0% parameter description coverage, but the single parameter task_id is a UUID whose purpose is obvious from context. Description does not add explicit parameter documentation, but the clarity of the tool's purpose compensates somewhat.

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 ('Mark a task as in_progress and record start time') and the resource ('task'). It also explains the state machine transition (pending → in_progress), which differentiates it from siblings like cph_task_complete and cph_task_cancel.

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

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

Explicitly states 'CALL THIS BEFORE writing any code or making any changes for this task' and explains why (hook system requires in_progress task for file writes). Also notes the only valid state transition from this tool.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds no further behavioral context beyond the purpose. It does not 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?

The description consists of two concise sentences with no redundant information. 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?

Despite having 6 parameters (2 with enums) and no output schema, the description omits any detail about parameter usage, return values, or behavioral side effects. This leaves significant 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?

Schema description coverage is 0%, yet the description provides no explanation for any of the 6 parameters. The agent receives no additional meaning beyond what the schema's names and types imply.

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 'Update task fields,' which is a specific verb+resource combination. It effectively distinguishes itself from siblings by noting 'For starting/completing, prefer task_start and task_complete.'

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 when to use alternative tools ('For starting/completing, prefer task_start and task_complete'), providing clear when-not-to-use guidance with named 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 and idempotentHint. Description adds behavioral context: inference from gaps, non-direct observability, and a caveat explaining inference limitations, which exceeds annotation coverage.

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 front-loaded with summary, followed by clear explanation of inference method and returns. Each sentence adds value; minor redundancy in Args section 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?

No output schema, but description explains return types (per-turn breakdowns, aggregate stats, tool baselines, caveat). Input schema covers all parameters. Inference method is explained, providing sufficient context for correct usage.

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

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

Schema description coverage is 67%, so baseline is 3. The description repeats parameter meanings from schema (e.g., 'Filter to a specific session') without adding new semantics beyond the inference 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?

Description clearly states 'Get inferred thinking-time breakdown for recent turns', specifying verb and resource. It distinguishes itself from sibling tools by focusing on thinking time inference, which is unique among the listed 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?

Description explains how inference works (initial gap, interleaved gaps, final gap) and what is returned, providing clear context. However, it lacks explicit guidance on when to use this tool versus alternatives, though no direct sibling exists.

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, destructiveHint, idempotentHint, and openWorldHint, covering safety and side effects. The description complements these by detailing what the tool returns (annotated list with specific fields), adding behavioral context beyond annotations without contradiction.

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

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

Description is extremely concise, with a clear first sentence stating the purpose, followed by a structured bullet list of return fields and a usage note. Every sentence adds value with 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 simple input schema (one optional param) and no output schema, the description adequately covers what the tool returns and why to use it. It could mention pagination or limits, but for a read-only overview tool, the provided information 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?

Schema coverage is 100% for the single optional parameter (workflow_id), with a clear description in the schema. The tool description adds no additional semantics about the parameter, but this is acceptable given the schema does the job. Baseline score 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?

Description clearly states it shows active agents/developers and their current tasks, blockers, and status. The verb 'Show' combined with specific fields (status, task, blocker) provides a precise resource and scope. It distinguishes itself from sibling tools like cph_task_list or cph_status by focusing on active session overview with team state.

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 advises 'Use this to understand team state before starting work,' giving clear context for when to invoke. While it doesn't list when not to use or alternatives, the context from sibling tools (e.g., cph_blocker_list for blockers, cph_task_list for tasks) makes the guidance 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?

Annotations are minimal (non-readOnly, non-destructive), and the description adds behavior: creation returns a workflow ID that should be saved in CLAUDE.md. It also explains integration with cph_detect_workflow. No contradictions with annotations.

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

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

The description is concise, with a clear one-line summary followed by bullet-pointed parameter explanations. Every sentence adds value, and it is front-loaded with the 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?

Given the tool has three parameters, no output schema, and minimal annotations, the description fully covers creation workflow, usage hints, parameter details, and return value expectations. No 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?

With only 33% schema description coverage, the tool description adds substantial meaning: examples for name, scope for description, and auto-detection purpose for git_branch_pattern. This compensates well for the schema gaps.

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 workflow, a project container for tasks, blockers, and decisions. It distinguishes from sibling tools like cph_workflow_list and cph_workflow_update by using 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?

The description explicitly advises creating one per feature branch, sprint, or meaningful engineering effort, giving clear context. However, it does not provide explicit exclusions or alternatives beyond referencing cph_detect_workflow.

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 read-only, non-destructive, idempotent behavior. Description adds return format (array with ID, name, status) and absence of task counts. Lacks pagination or ordering details, but overall good.

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 waste, front-loaded purpose and guidance.

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

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

With one optional param, rich annotations, and no output schema, the description covers return structure and key distinction from sibling. Missing default behavior (no filter returns all?) and ordering details, but minor.

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 parameter 'status' has enum fully defined in schema. Description adds minimal value by mentioning filtering by status but no extra semantics 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?

The description clearly states 'List workflows filtered by status' with verb, resource, and filter. It distinguishes from sibling cph_workflow_summary by noting no task counts.

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 'No task counts (use cph_workflow_summary for that)', providing clear guidance on when to use an alternative.

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 safe, read-only, idempotent behavior. The description adds valuable context: it aggregates multiple data types and shows dead ends. No contradictions with annotations, and it provides insight beyond what annotations offer.

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 fairly concise, with key information upfront and bullet points for use cases. It could be slightly tighter, but overall it avoids unnecessary verbosity while covering essentials.

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 (reconstructing full history), the description provides a good overview but lacks detail on the output format. No output schema exists, so describing the reconstruction object's structure would enhance 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?

The input schema has one parameter (workflow_id, UUID). Schema description coverage is 0%, but the tool description does not elaborate on the parameter. Since it's a simple, standard UUID, the lack of further explanation is acceptable but could be improved with a note on validity.

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 reconstructs full workflow history for handoff/review. It lists aggregated components (tasks, decisions, blockers, etc.) and identifies dead ends. However, it could more explicitly distinguish from similar tools like cph_workflow_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?

Explicitly lists three use cases: handoff, review, debugging. This provides clear guidance on when to use. However, it does not mention when not to use or suggest alternative tools, which would strengthen the dimension.

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, destructiveHint=false, idempotentHint=true, so the safe, read-only nature is established. The description adds clarity on what the tool returns (specific counts and ratios), supplementing 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?

Three precise sentences: purpose, return data, usage guidance. No unnecessary words or redundant information. Each sentence 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?

For a simple read-only tool with one parameter and no output schema, the description covers purpose, return details, and proper usage context thoroughly.

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 0% description coverage and a single parameter 'workflow_id' with no explanation beyond its type and UUID format. The description does not elaborate on how to obtain or use this ID, leaving the agent with no 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 explicitly states the action ('Get a full status summary') and the resource ('workflow'), with specific return values (task counts, blocker count, etc.). It clearly distinguishes from sibling tools like cph_workflow_list and cph_workflow_reconstruct.

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 direct guidance: 'Use this when a user explicitly asks for project status. Don't call proactively.' This tells the agent both when and when not to use it, which is exemplary.

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 the tool is not read-only (readOnlyHint=false), not destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds no further behavioral context beyond stating it updates fields. It does not mention side effects, such as whether omitted fields remain unchanged or the impact of different status values.

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 (12 words) that efficiently conveys what the tool updates. It is appropriately front-loaded and contains no unnecessary words. However, it could be slightly more structured with bullet points for 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 complexity of 5 parameters (all undocumented in schema) and no output schema, the description is insufficient. It does not explain the effect of updating specific fields, return values, or error conditions. An agent would lack crucial context 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%, so the description should compensate by explaining parameter meanings. It merely lists the parameter names (name, description, status, git_branch_pattern) without adding any semantics, constraints, or format details. For example, it does not mention that status has an enum or that workflow_id is required.

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 'Update' and the resource 'workflow', and lists specific fields (name, description, status, git branch pattern) that can be updated. This distinguishes it from sibling tools like cph_workflow_create and cph_workflow_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?

The description provides no guidance on when to use this tool versus alternatives such as cph_workflow_create or cph_workflow_reconstruct. There is no mention of prerequisites, when not to use it, or typical use cases.

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