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

Description claims idempotency ('Idempotent — re-running refreshes artifacts'), but annotations set idempotentHint: false. This is a direct contradiction, warranting a score of 1. Other behavioral details are provided but overridden by the inconsistency.

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 single paragraph, front-loaded with main purpose. Every sentence adds value, no 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?

Comprehensive description covering use case, idempotency, filesystem impact, and prerequisites. Output schema exists so return values are not 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 covers 100% of parameters. Description adds default values (project_root, scope) but no syntactic or usage details beyond schema. Baseline of 3 is appropriate.

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

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

Description clearly states the tool wires ControlKeel into the agent host, installing hooks and artifacts. It distinguishes from sibling ck_mcp_discover with specific guidance.

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 when to use (after one-line MCP install when host lacks hooks) and suggests using ck_mcp_discover first for host ID. Provides clear context and 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?

The description fully discloses behavior: explains that estimate and status are read-only, commit is a write operation that deducts from session budget, and mentions optional token overhead attachment. Annotations only provide hints, but the description gives concrete behavioral details 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?

Four concise sentences that efficiently convey purpose, modes, usage guidance, and parameter hints. Front-loaded with key information, no redundant or vague phrasing.

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

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

Given the complexity (three modes, 14 parameters, nested objects), the description covers all essential aspects: mode behavior, required params per mode, integration with token overhead, and link to sibling tool. Has output schema (context says true), so return values are documented elsewhere.

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?

While schema covers all parameters, the description adds crucial context: specifies required parameters for commit mode (session_id, estimated_cost_cents, provider, model, input_tokens, output_tokens) and explains include_token_overhead requires project_root. This goes beyond 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's purpose: 'Estimate, record, or check the cost of an agent operation against session and daily spend budgets.' It explicitly describes three modes (estimate, commit, status), distinguishing it from sibling tools like ck_cost_optimizer.

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

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

Provides explicit guidance: 'Check ck_budget before expensive multi-agent work or large model calls' and 'Use ck_cost_optimizer for model price comparisons without recording spend.' This clearly indicates when to use this tool and 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?

Description adds moderate behavioral context beyond annotations: it indicates a mutating operation ('Create') and what is captured, but does not disclose side effects, authorization needs, or whether earlier checkpoints are affected. Annotations are minimal, so description carries burden.

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

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

Single sentence, direct and informative with no redundant words. All information is front-loaded and essential.

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 (1 required, 1 enum) and an output schema, the description is too brief to fully guide usage. It lacks parameter details and usage scenarios, but is adequate for a simple create operation. The output schema likely documents return values, partially compensating.

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 80% description coverage (4 of 5 parameters described). The description adds no additional meaning to any parameters, relying on schema. Baseline 3 is appropriate as no further value 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?

Clear verb 'Create' and specific resource 'workspace checkpoint' with details of contents (git state, workspace context, metadata) and purpose (migration or rollback), distinguishing it from sibling tools like ck_checkpoint_restore.

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 implies usage for creating checkpoints but provides no explicit guidance on when to use this tool versus alternatives such as ck_rollback or other snapshot tools, nor any conditions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds minimal context by specifying that it lists checkpoints for a session, but does not disclose any additional behavioral traits like sorting, pagination, or limits on results.

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

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

The description is a single, clear sentence that efficiently conveys the tool's purpose without any superfluous 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?

While the description covers the basic functionality, it omits details such as the behavior of the 'limit' parameter and the structure of the output (though an output schema exists). Given the tool's simplicity and annotation support, it is adequate but not fully comprehensive.

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

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

The description only restates the optional type filter from the schema. It does not add meaning for the 'limit' parameter (which lacks a schema description) or elaborate on 'session_id'. With 67% schema coverage, the description fails to compensate for the missing parameter documentation.

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

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

The description clearly states the verb 'List' and the resource 'checkpoints', with scope 'for a session' and optional filter by type. This distinguishes it from sibling tools like ck_checkpoint_create or ck_checkpoint_restore.

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

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

The description does not provide any guidance on when to use this tool versus alternatives, such as ck_checkpoint_restore or ck_checkpoint_create. There is no mention of when not to use it or what conditions favor 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 provide destructiveHint: true and readOnlyHint: false, but the description adds little beyond 'Restore'. It does not disclose side effects, whether the restore is additive or replacement, what gets destroyed, or error conditions. For a mutation tool, more behavioral context is needed.

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

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

Single sentence, no redundant words, front-loaded with the primary action. Efficient and clear.

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

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

Core action is stated, but missing context such as prerequisites (e.g., checkpoint must exist), behavior on conflict, and effect on current session state. Output schema exists but does not fully compensate for the lack of behavioral 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 already describes 2 of 3 parameters (checkpoint_id and session_id), but 'strict' lacks description. The tool description does not add any additional parameter semantics. Baseline is 3 due to high schema coverage.

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

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

The description specifies the verb 'Restore', the resource 'session state from a previous checkpoint', and the action 'updating session metadata'. It clearly distinguishes from sibling tools like ck_checkpoint_create and ck_checkpoint_list.

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

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

No guidance on when to use this tool versus alternatives, no prerequisites or conditions mentioned. The description only states what it does without context for decision-making.

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. The description reinforces 'Read-only' and adds behavioral details about detail_level behavior and token efficiency. No contradictions; adds value 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?

The description is multi-sentence but every sentence adds value: purpose, components, parameter guidance, usage timing, sibling alternative. Efficient and front-loaded, though slightly verbose; still earns its length.

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, rich input schema, and many sibling tools, this description is thorough. It lists return components, explains parameter trade-offs, gives usage context, and covers edge cases (e.g., automatic session resolution). No output schema needed for explanation.

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 documents all 4 parameters with 100% coverage. The description adds defaults (compact for detail_level, session_id defaults to active bound session, project_root for resolution), providing meaning beyond the schema's definitions.

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

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

The description uses a specific verb ('Fetch') and resource ('full governed session state'), enumerating the components (mission, budget, findings, etc.). It explicitly distinguishes from the sibling tool ck_context_pack by directing when to use each, making the purpose unmistakable.

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

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

Provides clear guidance: 'Call ck_context at the start of every task to reacquire state' and specifically recommends ck_context_pack for focused retrieval. Also explains when to use compact vs full detail_level, giving explicit 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?

Description states 'Read-only' which aligns with annotations (readOnlyHint=true, destructiveHint=false). It also explains default behaviors for omitted query and detail_level. Adds value beyond annotations by clarifying synthesis of query and default detail_level.

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: first states purpose, second outlines parameters, third gives usage guidance. No redundant words. All information is front-loaded and critical for agent decision.

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 6 parameters, output schema, and annotations, the description covers purpose, parameter behaviors, defaults, and usage context. It is complete and does not need to explain return values due to 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 description coverage is 83%, so baseline is 3. Description adds meaningful defaults and behavior for query (synthesized when omitted), top_k (default 5), and detail_level (compact default). This enriches understanding beyond the schema descriptions.

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

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

The description clearly states the tool builds a compact, citation-enriched context bundle. It uses specific verbs and resources ('Build a ... context bundle') and distinguishes itself from the sibling tool ck_context by specifying use cases (mid-task vs session 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 guides when to use this tool over ck_context: 'Prefer ck_context_pack over ck_context when you need a focused, query-driven bundle for a specific sub-task rather than the full session snapshot. Use ck_context at the start of a session... use ck_context_pack mid-task.' This provides clear context and 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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds behavioral context by describing real-time event streaming and the collaborative aspect, which aligns with the annotations. It does not contradict them.

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

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

The description is three sentences, front-loaded with the primary purpose, and efficiently covers the key modes. No extraneous 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 complexity (7 parameters, nested objects) and that an output schema exists, the description provides sufficient high-level context. It could be more explicit about parameter usage per mode, but the schema covers 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 coverage is 100% and parameters are already described. The description adds value by summarizing the modes but does not elaborate on other parameters like actor, event_type, limit, payload, session_id, task_id beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a real-time collaborative channel for human actions streaming to the agent, explaining that agents can see human viewing, editing, approving. It distinguishes itself from siblings by specifying modes (subscribe, publish, presence, history) and the collaborative nature.

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 four modes and what each does (receive events, emit event, who is active, recent events), providing clear context for when to use. However, it does not explicitly state when not to use or contrast with 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description confirms 'Read-only — no budget records are written' and outlines two modes with their outputs (suggest: optimization tips; compare: price breakdown). This adds value beyond annotations without contradicting them.

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

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

The description is three sentences: purpose and read-only status, mode definitions, and usage guidance with an alternative. It is front-loaded, efficient, and every sentence adds actionable value 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 7 parameters and an output schema, the description covers the core logic (two modes, parameter requirements, return types) and provides a real-world usage scenario. While it omits the 'spending' parameter, the overall completeness is high for the tool's 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?

With 71% schema description coverage, the description clarifies the critical parameter 'mode' and maps other parameters to modes (e.g., session_id for suggest; task_description, estimated_tokens, top_provider, top_model for compare). However, the 'spending' parameter is not mentioned, leaving a small 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's function: 'Get cost optimization suggestions or compare AI provider/model prices for a task.' It specifies two distinct modes (suggest, compare) and contrasts with sibling tool ck_budget for recording spend, making the purpose 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?

Explicit usage guidance is provided: 'Use ck_cost_optimizer before choosing a model for expensive multi-agent work; use ck_budget to record and enforce spend limits.' The description details which parameters to pass for each mode (session_id for suggest, task_description/estimated_tokens/top_provider/top_model for compare), offering clear when-to-use and when-not-to-use information.

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 states 'Mutates session state to reflect the delegation,' which aligns with annotations (readOnlyHint=false, destructiveHint=false). It also explains the four modes and their behaviors, providing transparency beyond the annotations.

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

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

The description is four sentences, front-loaded with the core purpose, and each sentence adds essential information without redundancy. It is a model 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 the tool's complexity (5 parameters, output schema exists), the description covers purpose, usage, modes, and alternatives. It lacks explicit mention of error conditions or prerequisites but is otherwise 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 80%, and the description adds meaning by explaining the four modes (e.g., 'auto: ControlKeel picks the best agent'), which is not in the schema. However, it does not elaborate on the purpose of task_id, session_id, or project_root beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Hand off a governed task or session to another AI agent, transferring governance context.' It specifies the verb 'hand off' and the resource, distinguishing it from siblings like ck_route.

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?

Explicit guidance is provided: 'Call ck_route first to identify the best agent, then ck_delegate to transfer. Prefer ck_route when you only need a recommendation without transferring; prefer ck_delegate when you are ready to hand off execution.' This clearly indicates when to use this tool vs the 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?

Discloses that analyze and dns_guide are read-only, generate_files is a write operation (creates files). Mentions dry_run to preview writes. Annotations (readOnlyHint=false) are consistent; description adds detail beyond them.

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

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

Four concise sentences: main purpose, mode summary, required parameter note, usage guidance. Front-loaded and efficient with no extraneous content.

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

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

Covers all modes, their behaviors, and expected outcomes (recommendations, file generation, DNS instructions). With output schema present, no further return details needed. Complete for a multi-mode 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 beyond schema: explains dry_run purpose ('preview what would be created without writing files') and when to use it (with generate_files). Clarifies project_root 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?

Description states specific verb-resource pairs for three modes: analyze (analyze stack), generate_files (generate configs), dns_guide (return DNS instructions). Clearly distinguishes from sibling tool ck_budget.

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: 'before deploying a new project or when setting up CI/CD for the first time'. Recommends alternative 'ck_budget' for cost checks. Also describes mode-specific 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?

Description adds value over annotations by detailing sandbox defaults, denial of capabilities, validation step, and dry_run support. 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?

Single sentence efficiently conveys core purpose and key constraints 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 the complexity (12 params, output schema exists), the description covers essential behavior. Could detail timeout/output handling but is sufficient with schema support.

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 75%, so baseline 3 is appropriate. Description mentions dry_run and sandbox but does not elaborate on other parameters beyond schema.

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

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

The description clearly states the tool executes code in a non-local sandbox, specifying Docker as default, and lists restrictions. It distinguishes from siblings as no other tool performs code execution.

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 (for code execution in a sandbox) and what it denies, but does not provide explicit alternatives or when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that the tool lists read-only artifacts and supports keyword search, which is consistent but not significantly beyond annotations. No contradictions.

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

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

The description is two sentences long, front-loaded with the main action. Every sentence adds value 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 an output schema exists and schema coverage is complete, the description covers the core functionality. However, it could briefly mention how other parameters like session_id affect results. Still, it is largely complete 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 coverage is 100%, so parameters are already described. The description adds a use case for the query parameter but does not explain others. This provides some additional 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 lists recent prior sessions and read-only experience artifacts, using a specific verb ('List') and resource. However, it does not explicitly differentiate from sibling tools like ck_experience_read or ck_experience_search.

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

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

The description gives an example use case for the query parameter but does not specify when to use this tool versus alternatives, nor when not to use it. The usage is implied rather than explicit.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds archive context and artifact types, but no additional behavioral traits beyond what annotations convey.

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, front-loaded with main action, 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?

With output schema present and annotations covering safety, description sufficiently explains purpose and scope. Minor omission of source_session_id requirement, but still 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 description coverage is 80% (4 of 5 parameters documented). Description does not add parameter-specific 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?

Description clearly states verb 'read', resource 'prior-run artifact', and lists specific artifact types. Distinguishes from sibling tools like ck_experience_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?

Implies usage for reading prior-run artifacts, but provides no explicit when-to-use or when-not-to-use guidance, nor mentions alternatives.

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

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

Annotations already indicate readOnlyHint and idempotentHint, making safety clear. The description adds value by specifying it returns ranked results with citations, which is not obvious from annotations alone. 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?

Two sentences plus two example questions, all front-loaded. Every sentence adds value without extraneous 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 presence of an output schema, description appropriately focuses on scope ('current workspace') and content type ('findings and tasks'). It is fully sufficient for a search tool.

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

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

Schema coverage is 100% (all parameters described), so baseline is 3. The description does not add extra meaning beyond the schema; it merely restates 'freeform' for the query parameter.

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

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

The description clearly states it performs freeform full-text search across findings and tasks, returning ranked results with citations. This distinguishes it from siblings like ck_experience_index (indexing) and ck_experience_read (reading specific entries).

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 concrete examples of questions it answers (e.g., 'has this deployment pattern caused a blocked finding before?'), giving clear context for when to use it. However, it does not explicitly mention when not to use it or 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 set readOnlyHint=false, destructiveHint=false, idempotentHint=false, indicating this tool can create or modify data. The description adds value by mentioning auto-redaction of PII and rate limit tracking, but does not fully specify side effects of each mode or authorization needs.

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 phrases covering purpose, features, and modes. Every sentence adds unique value without redundancy, and the core purpose is front-loaded.

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

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

Given the tool's complexity (12 parameters, output schema present, nested objects), the description provides sufficient high-level context for an agent to select the correct mode and understand the tool's role. The presence of an output schema reduces the need to describe return values. A bit more detail on mode-specific prerequisites would elevate 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?

100% schema description coverage sets a baseline of 3. The description does not add parameter-level details beyond what the schema provides, though it contextually explains modes that influence parameter usage (e.g., 'limit' is relevant for top_services mode).

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

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

The description clearly defines the tool's purpose: 'Track and govern agent interactions with external SaaS APIs.' It lists specific capabilities (rate limits, cost attribution, PII redaction) and enumerates operational modes (record, summary, rate_limit_status, top_services), making it distinct from sibling tools that focus on other domains.

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 names the four modes and their purposes, guiding the agent on when to use each (e.g., 'record (log an interaction with auto-redaction)'). However, it does not provide explicit 'when not to use' guidance or compare directly to siblings like ck_cost_optimizer or ck_observability.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about operating on 'recent session traces in the same workspace' and returning 'eval candidates', which supplements the 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?

Single, well-structured sentence with the verb front-loaded. No wasted words.

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

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

Given the tool's complexity (4 parameters, output schema exists), the description effectively conveys core purpose and what it returns. It does not clarify 'recent' or clustering details, but output schema likely covers that.

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%, so the burden on description is lower. The description does not add extra parameter meaning beyond the schema, resulting in baseline score.

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 (cluster) and resource (failure modes from session traces) and mentions outcome (return reusable eval candidates). It clearly distinguishes from siblings like ck_observability or ck_validate.

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 implies usage for analyzing failures but does not explicitly state when to use vs alternatives or exclude other cases. No when-not or alternative tool suggestions.

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 'mode=create' persists a finding and 'mode=resolve|dismiss|escalate' dispositions existing findings. It mentions that using 'allow' auto-resolves matching open/blocked findings, which provides behavioral insight beyond annotations. Annotations indicate a write operation (readOnlyHint=false), and the description confirms it 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?

The description is moderately long but each sentence adds necessary information. It front-loads the main action and mode distinction, then details parameters and returns. Minor redundancy could be trimmed, but overall it is efficient.

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

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

The description covers all relevant aspects: modes, required fields, default behaviors, return values, and sibling differentiation. With output schema present, the return structure is clarified. For a tool with 13 parameters and multiple modes, the description is thorough and leaves no critical ambiguity.

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 92% (high), so baseline is 3. The description adds value by explaining defaults (decision defaults to warn), special behavior (allow auto-resolves), and how bulk disposition works via rule_id/category/status, which is not fully detailed in the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Record or disposition a governed finding.' It explains both create and disposition modes, and distinguishes from sibling 'ck_memory_record' by specifying that ck_finding is for policy findings while the sibling is for general knowledge.

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

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

The description provides explicit guidance on when to use each mode (create vs. disposition) and lists required fields for create. It directly recommends using ck_finding for policy findings and ck_memory_record for general knowledge, offering an alternative. It does not explicitly state when not to use the tool, but the 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?

Annotations already provide readOnlyHint and idempotentHint. The description adds context by clarifying that query is a path fragment or glob pattern and that the search is non-destructive. No contradictions; behavioral traits are well-explained 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?

The description is concise (several sentences) and well-structured: purpose, read-only note, parameter explanations, usage guidelines. No redundant or filler text. Front-loaded with the core 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?

Given the tool has 5 parameters, an output schema, and rich annotations, the description covers all essential aspects: what it does, parameter semantics, scope, and when to use alternatives. It feels complete 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 for query ('path fragment or glob pattern'), path ('scopes search to subdirectory'), and limit ('default 50'), which go beyond the schema. Schema description coverage is 80%, so baseline 3 is elevated to 4 due to these clarifications.

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

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

The description starts with a specific verb and resource: 'Find files or directories whose path contains a given fragment, searching within the bound project root.' It clearly distinguishes from sibling tools by naming ck_fs_grep and ck_fs_read for alternative use cases.

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 this tool ('Use ck_fs_find to locate files by name or path') and provides alternatives for content search (ck_fs_grep) and reading known files (ck_fs_read). It also declares the tool is read-only, indicating it should not be used for modifications.

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 declares read-only behavior ('Read-only — no files are modified'), explains the fixed-string default with option to switch to regex, describes output format (matching lines with file path and line numbers), and notes the default limit (50). Annotations already indicate readOnlyHint and idempotentHint, and the description aligns perfectly 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?

The description is concise with five sentences, each carrying essential information. It front-loads purpose, then covers behavior, parameter hints, output, and sibling differentiation. 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?

Given the parameter count of 7, high schema coverage, and presence of an output schema, the description covers all key aspects: purpose, read-only safety, search modes, scope, result limits, output format, and alternatives. It is self-contained and leaves no critical gaps for agent decision-making.

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 high (86%), so baseline is 3. The description adds meaning beyond schema by explaining that query uses fixed-string search by default with the option fixed_strings: false for regex, that path can be a relative directory or glob, and that limit caps results with a default of 50. These clarifications help an agent select correct parameter values.

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

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

The description clearly states the tool's purpose: 'Search file contents using grep-style pattern matching' with a specific verb and resource. It explicitly distinguishes from siblings by naming ck_fs_find and ck_fs_read for alternative 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 explicit when-to-use guidance: 'Use ck_fs_grep to find code patterns or strings inside files.' It also tells when not to use it by referencing sibling tools for name-based search or file reading. It explains default behavior (fixed-string) and how to change to regex.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description reinforces that it is read-only and states that no files are modified. It also clarifies the path parameter behavior (omit to list root). No contradictions.

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

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

The description is extremely concise: two sentences that cover purpose, read-only nature, path guidance, and sibling tool references. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity, annotations provide safety and idempotency, and an output schema exists, the description is complete. It covers what, how, and when to use, plus alternatives. 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?

The schema has 3 parameters with 67% description coverage (path lacks description). The description adds meaning for 'path' by explaining it is a relative directory path and that omitting it lists the project root. This compensates for the missing schema description.

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

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

The description clearly states the action (list), the resource (files and directories), and the scope (inside bound project root). It also distinguishes from sibling tools like ck_fs_find, ck_fs_read, and ck_fs_grep.

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 tells when to use this tool ('browse directory structure') and provides direct alternatives for other tasks (ck_fs_find, ck_fs_read, ck_fs_grep). It also notes the read-only nature.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description reinforces with 'Read-only — no files are modified or created' and adds windowed read behavior. No contradiction. Adds 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?

Four sentences, front-loaded with purpose, no redundant words. 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?

Given output schema exists and annotations cover safety, the description covers usage, parameters, and alternatives well. Minor omission: no mention of error handling for missing paths or permissions, but overall 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 80%; description adds meaning: path must be relative to project root, start_line is 1-indexed, max_lines enables windowed reads, omit both for full file. The schema lacks description for max_lines, so description 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 states 'Read a file from the bound project root' with clear verb and resource, and explicitly distinguishes from sibling tools (ck_fs_find, ck_fs_grep, ck_fs_ls).

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 when-to-use guidance: 'Use ck_fs_read to inspect a file at a known path' and lists alternatives for locating, searching, and listing. Also explains when to use start_line/max_lines for windowed reads vs. omitting for full file.

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

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

Annotations already indicate destructiveHint=true. Description adds conditional behavior (blocked findings prevent commit), which adds value. 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?

Five sentences, front-loaded with main action. No redundant information. Every sentence adds value.

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

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

Covers validation, conditional commit, output, prerequisite, and limitation. Output schema exists, so return values are covered.

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 67% but description does not clarify the undocumented 'session_id' parameter. Message and project_root are partially implied but not explicitly linked to schema 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?

Clearly states it validates a commit message and executes git commit if validation passes. Distinguishes from siblings by specifying prerequisite (ck_git_status) and what it does not do (no push). Specific verb+resource+conditions.

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 to use ck_git_status first and notes that git push is separate. Provides 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description reinforces read-only behavior and adds that it returns diff text and CK validation findings, which provides 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?

The description is concise with three main sentences plus a usage triplet. It front-loads the core purpose and read-only nature, with 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 that an output schema exists and annotations cover safety, the description covers core usage, parameter behavior, and distinguishes alternatives. The only gap is the session_id parameter, but overall it is complete enough for correct tool 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 75%, and the description adds meaning for base_ref and head_ref by explaining they are git refs and can be omitted. However, the session_id parameter lacks explanation in both schema and description, so the description only partially compensates for the coverage 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 generates a git diff and runs CK validation. It explicitly says 'Read-only — no commits are created' and distinguishes from siblings like ck_git_status and ck_git_commit.

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

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

The description provides explicit when-to-use guidance: 'Use ck_git_diff to review changes before committing or submitting a review.' It also gives clear alternatives: 'Use ck_git_status for a summary without the full diff. Use ck_git_commit to create the commit after reviewing.' Additionally, it explains parameter usage for base_ref and head_ref.

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

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

Description declares 'Read-only and side-effect free — no findings are created or modified', which aligns with annotations (readOnlyHint, idempotentHint, destructiveHint). Adds context about what the tool does not affect, enhancing transparency 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 sentences: purpose/output, read-only declaration, usage guidance. Every sentence adds value; no fluff. Front-loaded with the primary function.

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, safety, usage guidelines, and alternatives. Output schema exists but is not shown; description adequately describes return types. Only minor gap is parameter documentation, but overall complete for a read-only tool.

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

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

Schema description coverage is 50%; only project_root has a description. Session_id is not described in schema or in the tool description. The description does not explain the role or format of session_id, leaving ambiguity. Parameter semantics are weak.

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 retrieves git working tree status correlated with CK governance findings, listing specific outputs (staged/unstaged/untracked files, blocked/open findings). Differentiates from sibling tools ck_git_diff and ck_git_commit by mentioning alternatives.

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

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

Explicitly states when to use ('before ck_git_commit') and when to use alternatives ('prefer ck_git_diff for diff content; prefer ck_git_commit when ready to commit'). Provides clear context and 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?

Describes three modes with different read/write behaviors, explains horizon scope, and does not contradict annotations (readOnlyHint=false indicates writes are possible).

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

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

Single paragraph is clear and front-loaded, but could use slight restructuring (e.g., bullet points) for easier scanning. No 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 complexity (3 modes, many optional params) and presence of output schema, description covers all major behavioral aspects and usage context comprehensively.

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 high (88%); description adds meaning by explaining mode-dependent required fields, horizon roles, and differentiation from sibling. Adds value beyond schema.

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

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

Description clearly states it records/lists/updates goals, specifies three modes, and distinguishes from sibling ck_memory_record by stating use case.

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 when-to-use guidance for each mode, required parameters per mode, and compares with ck_memory_record for when not to use 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that loading can be bulk and 'governed,' but does not disclose additional behaviors like authentication needs or rate limits. The annotation coverage reduces the burden, but the description adds moderate value.

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 fallback purpose, and every word adds value. 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?

The description covers the main purpose and bulk loading capability. With an output schema present and annotations covering safety, the description is adequate for an AI agent to understand the tool's primary use case, though it does not detail all parameters beyond uris.

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 75%, with session_id lacking a description. The description provides a URI format example (skills://<name>) that adds clarity to the 'uris' parameter, but it does not compensate for the missing description of session_id. Overall, the description adds some meaning but does not fully offset the schema gap.

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

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

The description clearly states the tool loads CK resource URIs, especially skills, and explicitly positions it as a fallback for clients that do not support MCP resources or native bulk skill loading. This distinguishes it from sibling tools like ck_skill_load and provides 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 states when to use this tool: 'Fallback for clients that do not support MCP resources or native bulk skill loading.' This provides clear context but does not name specific alternative tools, leaving some room for interpretation.

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

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

Annotations provide no safety profile (all false), so the description carries the full burden. It discloses behavioral traits: the tool modifies state (non-read-only), is not destructive, and not idempotent. It adds context about freezing verifier paths, separating mutable paths, enforcing stop conditions, and requiring audited rollbacks for rejected iterations, which goes 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?

The description is three sentences, front-loaded with the core purpose. It is dense but avoids verbosity. Minor improvement could be achieved with bullet points for modes, but overall it is 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?

Despite the tool's high complexity (51 parameters, many enums, nested objects, output schema), the description does not explain return values, mode-specific parameter requirements, or the relationships between parameters. It assumes significant domain knowledge about 'bounded iterative loops,' 'verifier paths,' and 'artifact longevity,' leaving the agent underinformed.

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 2% (one parameter documented). The description mentions the 'mode' parameter and its enum values but does not explain any other parameter's semantics, meaning for the remaining 49 parameters the agent must rely solely on names and types. The description should compensate for low coverage 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's purpose: 'Create and govern a bounded iterative loop without executing worker code.' It lists specific actions (freeze verifier paths, separate mutable paths, classify artifacts, enforce stop conditions) and modes (create, record, status, stop, promote), making the verb+resource distinct from sibling tools.

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

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

The description implies usage context (governing iterative loops) but does not explicitly state when to use this tool versus alternatives among the many sibling tools. No exclusion criteria or comparisons are provided, leaving the agent to infer 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?

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds useful context: it queries an external endpoint and enables progressive discovery. 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?

Two sentences, front-loaded with the core action, no redundant information. Every word serves a 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?

The description is complete for a discovery tool with a well-documented schema and output schema (not shown but present). Minor gap: does not mention error handling or output format, but output schema covers return values.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description does not add extra meaning beyond what is in the schema, meeting the baseline of 3.

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

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

The description clearly states it auto-discovers tools from an external MCP server by querying its tools/list endpoint. It uses a specific verb+resource, and the purpose is distinct from sibling tools like ck_skill_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 implies use when needing to discover tools from an external server, but does not explicitly state when to avoid it or compare with siblings (e.g., ck_external_service or ck_skill_load). No when-not or alternative guidance.

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

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

Annotations provide safety info (not read-only, not idempotent, not destructive). Description adds behavioral context: marks as archived, not deleted, and is a write operation, enhancing transparency 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?

Description is concise (5 sentences), front-loaded with purpose, explains effect, input, usage, and alternative. Every sentence adds value with no 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?

Covers purpose, usage, parameter details, and alternatives. With output schema present, return values are explained elsewhere. Missing error conditions or permissions, but sufficient for an archive tool given annotations.

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

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

Schema description coverage is 67%. Description adds meaning for memory_id (explains its origin). session_id and project_root rely on schema descriptions, but the description compensates for the missing memory_id description.

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

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

The description clearly states it archives a memory record to exclude it from search results, specifies it's a write operation not deletion, and distinguishes from sibling tools like ck_memory_record and ck_memory_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?

Explicitly advises when to use (stale, superseded, no longer guiding) and when to use alternative (update via ck_memory_record), providing clear 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?

Discloses idempotency behavior (re-submitting same source_id updates rather than duplicates) and write operation, adding context beyond annotations. No contradiction with annotations except idempotentHint discrepancy.

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. All sentences are informative without redundancy. Slightly long but justified due to number of 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?

Covers key parameters (memory, record_type, source_id, tags) but not all 12 parameters (e.g., task_id, session_id, project_root). However, schema descriptions fill some gaps. Adequate for 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?

Adds meaning by explaining memory parameter can be plain string or object with body, title, summary, etc. Also explains record_type enum values. Schema coverage is 75%, so description compensates moderately.

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 'Write a governed memory record' and explains persistence to database. It distinguishes from sibling tools like ck_memory_search (retrieval) and references ck_finding and ck_goal for alternative use cases.

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?

Explicit guidance: 'Use ck_memory_record to persist knowledge that should survive session boundaries.' Also tells when to use alternatives: 'Use ck_finding for policy violations... Use ck_goal for durable multi-session intent.'

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

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

Description adds context beyond annotations: it is read-only, performs freeform text search across titles/bodies/tags, returns ranked records with citations and scores. Annotations already declare readOnlyHint=true and idempotentHint=true; description reinforces and elaborates.

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 purpose, then parameter details, then usage guidance. Every sentence is informative with no wasted words. Structure is clear and logical.

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 9 parameters, output schema present, and rich annotations, the description fully covers usage, parameters, and context. It explains when to use, what each parameter does, and the return format (ranked records with citations and scores). An agent can confidently select 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 89% high, yet description adds meaning: explains query as freeform text search, record_type filters by type listing options, top_k limits results with default 10, source_type and source_id filter by origin, detail_level options compact vs full. This adds significant value beyond schema.

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

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

Description clearly states 'Search governed typed memory for the current session to recover prior decisions, findings, proofs, and domain knowledge.' It uses a specific verb and resource, and distinguishes from siblings like ck_memory_record and ck_experience_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?

Explicitly provides when to use: 'Use ck_memory_search to retrieve what was recorded...' and when not: 'Use ck_memory_record to write new records. Use ck_experience_search for full-text search across findings and tasks workspace-wide.'

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, idempotentHint, destructiveHint. The description reinforces read-only behavior and adds extra context by listing excluded operations (e.g., benchmark execution, promotion mutation). No contradictions, and adds value 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?

The description is extremely concise, consisting of two sentences. The first sentence lists all report types, and the second clarifies read-only scope. No redundant information; every word earns its place.

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

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

Given the complexity of the tool (9 parameters, many enum values) and the presence of an output schema, the description adequately covers the core purpose and exclusions. It could be slightly more explicit about when to use specific report types, but overall sufficient for an agent to understand basic functionality.

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 high (89%), so the schema already documents most parameters. The description does not add parameter-level details but lists the report types, which overlap with the 'report' parameter enum. Baseline score of 3 is appropriate as the description does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool reads local observability reports, listing specific report types (sessions, loop status, problems, memory, costs, trends, evals, etc.). It also explicitly states what it does not do (no benchmark execution, draft approval, etc.), which helps distinguish it from sibling tools that perform those mutations.

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

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

The description provides explicit 'Read-only' statement and lists excluded operations, guiding agents not to use this tool for mutations. However, it does not explicitly contrast with specific sibling tools like ck_validate or ck_execute_code, leaving some implicit guidance. Clear context for read-only usage is given.

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

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

Discloses write vs read-only modes and mentions impact on other tools. Annotations lack behavioral details, so description adds value. Could further mention idempotency or side effects but is sufficient given output schema presence.

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 and well-structured, breaking down modes with clear bullet points. Every sentence adds value 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?

Covers all essential aspects: three modes, required parameters per mode, usage timing, and integration with other tools. Output schema handles return values, so no further detail 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?

Adds significant meaning beyond schema by mapping parameters to specific modes (e.g., 'For record mode: pass...') and enumerating outcome values. Schema coverage is 63%, so description compensates well for undocumented parameters.

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

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

Clearly defines three distinct modes (record, get_session, get_leaderboard) with specific verbs and resources. Distinguishes itself from siblings by focusing on outcomes and leaderboards, as evidenced by mention of feeding data to ck_route and ck_cost_optimizer.

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 usage context: 'Call after task completion before ending the session' and explains downstream dependencies. However, does not directly contrast with alternatives among siblings or state when not to use.

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

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

Annotations already indicate mutability (readOnlyHint=false). Description confirms write operation and return of an ID. No additional behavioral traits (e.g., side effects, permissions) are disclosed beyond what annotations imply.

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?

Approximately 7 sentences, front-loaded with purpose and usage. Each sentence adds value—purpose, return, parameters, usage context, retrieval alternative. No redundant phrasing.

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

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

For a tool with 11 parameters, 4 required, nested objects, and an output schema, the description covers the core purpose, workflow integration, and retrieval. The output schema exists but its details are not described; however, the description mentions the return value.

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 91%, so baseline is 3. Description lists required and some optional parameters with minimal elaboration (e.g., 'commit_sha to link results to a specific revision'). Does not add significant meaning beyond the schema's own 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 records external regression-test evidence and that it is a write operation creating a DB record, linking to proof bundles and release-readiness. It distinguishes its role by mentioning related tools (ck_review_submit, ck_memory_search) but does not explicitly differentiate from all 50+ siblings.

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

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

Explicit guidance to use after an external test run and before ck_review_submit, plus retrieving past results via ck_memory_search. Does not specify when not to use, 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds byte-range support, limits, and that it works on completed runs only. 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?

Concise but informative: 4 sentences that progressively build from purpose to parameters to decision logic. No redundant information.

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

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

With output schema present, description covers all necessary aspects: what it does, how to call it, what parameters mean, and when to use alternatives. Complete for its 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 coverage is 100%, but description adds crucial context: package_root origin, default and max values for peek_bytes and offset, and usage of result_ref (even though not in 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 peeks at stdout from a ck_delegate run, distinguishes it from loading full context, and specifies the key inputs (result_ref, package_root).

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 when-to-use (after ck_delegate), how-to-use (use result_ref and package_root), and decision criteria (use result_length to decide peek, pass, or skip). Mentions the RLM pattern.

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 is a write operation that updates the review record and unblocks or halts the execution gate. This adds behavioral context beyond the annotations, which correctly indicate it is not read-only, not idempotent, and not destructive. No contradiction with annotations.

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

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

The description is slightly long but well-structured, front-loading the core action and then providing parameter details and workflow context. Every sentence adds value, with no unnecessary 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 has 5 parameters (some nested) and an output schema, the description covers all aspects: purpose, parameters, workflow, and behavioral impact. It is comprehensive and does not leave 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 description explains each parameter's role and the relationship to ck_review_submit. However, the schema description for 'decision' mentions 'allow, warn, block, escalate' while the enum is 'approved/denied', creating a minor inconsistency that reduces clarity.

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 approves or denies a review, specifying the verb 'Approve or deny' and the resource 'submitted review'. It also distinguishes from siblings like ck_review_submit by noting it is called after submission.

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

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

The description provides explicit guidance: it is human-facing, agents should call ck_review_submit first, and after approval the agent proceeds, after denial the plan is revised. It clearly defines when to use this tool versus alternatives.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, confirming safe read-only behavior. The description adds context about the polling pattern and the return of status, notes, and URL, which goes 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?

The description is a single paragraph that efficiently conveys purpose, usage, and behavioral context without redundancy. It is appropriately front-loaded with the main action (fetch status) and then details. Could be slightly more streamlined, but it is effective.

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 output schema exists (though not shown), the description covers the key return fields (status, notes, URL) and usage pattern (polling). For a relatively simple read-only tool, this is complete enough. It could mention error handling or not-found cases, but it is sufficient.

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

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

With 67% schema description coverage, the description adds meaning by explaining the interaction between review_id, task_id, and review_type, particularly that review_type filters when task_id is used without review_id. This clarifies parameter usage 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 fetches the latest decision status, reviewer notes, and browser review URL, distinguishing it from sibling tools like ck_review_submit and ck_review_feedback. It specifies the resource and verb effectively.

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

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

The description provides explicit guidance on when to use the tool: with review_id or task_id, and explains that review_type filters when task_id is used. It also advises polling after ck_review_submit to check approval before proceeding. While it lacks an explicit 'when not to use' statement, the context is clear.

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