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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: the return format (lists of approaches, reasons, timestamps, ordered newest first), empty-list behavior, and the policy against re-attempting failed approaches. This goes well beyond the structured 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 and front-loaded: the main usage instruction appears in the first sentence, followed by a clear Args/Returns breakdown. Every sentence is necessary and informative, with no redundancy or fluff.

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

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

Given the tool's single parameter, existing annotations, and the included output schema, the description is fully complete. It covers when to use, what the parameter means, the return structure with ordering and empty-list handling, and the behavioral policy—all an agent needs.

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

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

The schema only defines 'task' as a string, but the description adds crucial meaning: 'The exact task string used with ledger_log_approach.' This clarifies the parameter's provenance and required exact match, significantly enhancing the schema's bare type definition.

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

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

The description clearly states the tool's purpose: to check known approaches (dead_ends, no_gos, works) for a task before retrying or re-planning. It distinguishes itself from sibling logging tools by being a read/check operation, and the specific verb 'check' plus resource 'approaches' makes it unambiguous.

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

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

The description explicitly instructs when to use the tool: 'Call this BEFORE retrying or re-planning a task.' It also provides a clear exclusion rule: never re-attempt an approach listed in dead_ends or no_gos unless new information invalidates the reason. This is direct, actionable guidance.

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

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

The description discloses return value format (id int), error behavior (ValueError for invalid tier and empty strings), and tier semantics. These details go beyond what annotations provide, offering actionable behavioral context.

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

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

The description is front-loaded with a one-sentence summary, then organized into Args, Returns, and Errors sections. It is concise, well-structured, and every sentence adds useful information.

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

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

Given the tool's modest complexity, the presence of an output schema, and annotations, the description fully covers purpose, parameters, return value, and error cases. It is complete enough for safe and correct invocation.

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

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

Schema only provides types, while description adds allowed tier values (0,1,2), example categories, non-empty constraints, and optionality of project. This significantly enriches parameter understanding, especially with 0% schema coverage.

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

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

The description clearly states it records a single autonomous action in a dev loop, with a specific verb and object. It distinguishes from sibling tools by specifying 'autonomous action' rather than dispatch or verdict, giving it a distinct purpose.

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

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

It provides clear context for when to use: logging any action the agent takes on its own initiative, tagged with a tier. It does not explicitly exclude other ledger tools, but the context is sufficient for an agent to choose this among siblings.

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

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

Beyond the annotations, the description discloses return format ('dict: {"id": int}'), error behavior (ValueError with message naming valid values), and the critical stable-task-identifier requirement. It also enumerates outcome values with meanings. This provides significant operational context beyond the sparse annotation flags.

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 organized with a strong opening sentence, then a practical usage note, and a well-formatted Args section. Each sentence provides necessary guidance with no filler. It is appropriately sized for a tool with four parameters and meaningful behavioral constraints.

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 when to use, what the parameters mean, what the return value is, and potential errors. The output schema already documents return structure, so the description need not repeat it. Sibling tools are mentioned via ledger_check_approaches, providing integration context. This is a complete, self-contained description.

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

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

With 0% schema description coverage, the description fully compensates. It explains task as a stable identifier to reuse across approaches, approach as a short non-empty description, outcome with the allowed enum and their implications, and reason as a required explanation. This is far more informative than the bare schema properties.

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

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

The description opens with 'Record the outcome of an approach tried (or considered) for a task.' This clearly specifies the verb (record), resource (approach outcomes), and scope (per task). It also distinguishes itself from siblings by referencing ledger_check_approaches as a companion and focusing specifically on approaches rather than actions or dispatches.

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

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

The description gives explicit when-to-use guidance: 'Record every failed approach IMMEDIATELY after it fails, and every deliberate NO-GO decision.' It explains the purpose (avoid re-discovering dead ends). However, it does not explicitly state when not to use this tool or name alternatives such as ledger_log_action, so it lacks formal exclusions but provides clear context.

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

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

The annotations indicate a write operation (readOnlyHint=false) but the description adds significant behavioral detail: the return dict with id and retry_count (and that retry_count counts PRIOR dispatches), the ValueError on empty fields, and the requirement to reuse the same task string. These details go beyond what annotations reveal.

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

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

The description is well-organized into purpose, usage, Args, Returns, and Errors sections. Every sentence adds value; there is no padding, and the structure makes it easy to scan.

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

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

The description accounts for usage, parameters, return value, and error handling. Given the tool's simple functionality and the explicit return/error details, the description is fully complete for an agent to select and invoke it correctly.

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

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

With 0% schema description coverage, the description fully compensates by providing meaningful definitions for each parameter: task (stable identifier, same string across retries), agent_type, model, and brief_summary, including examples for each.

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

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

The description opens with a specific verb ('Record') and resource ('a subagent dispatch'), explicitly stating its audit and retry tracking purpose. This clearly distinguishes it from sibling tools like ledger_log_action and ledger_log_verdict.

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 to call it 'every time a subagent is dispatched', establishing a clear usage context. It also ties to ledger_task_status for retry counting but does not explicitly name alternative tools for non-dispatch logging, so it stops short of full when-not 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 declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds valuable behavior beyond annotations: it returns a dict with 'ok' and 'task', and raises ValueError for invalid dispatch_id or verdict. It does not contradict annotations, and the idempotent hint is neither repeated nor undermined.

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

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

The description is well-structured with a clear one-sentence summary followed by Args, Returns, and Errors sections. It is concise for the amount of information it conveys; every sentence adds value, including error behavior and the return shape.

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 moderate complexity, the description is complete: it covers when to use it, all parameters, allowed values, return value, and error cases. The relationship to ledger_log_dispatch is explicit, making the tool's context within the ledger family clear. An output schema exists, but the description's Returns section still adds value by specifying the exact keys.

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

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

Schema description coverage is 0%, but the description compensates fully with an Args section that explains each parameter. It even lists the exact allowed values for 'verdict' ('CONFIRMED', 'REFUTED', 'PARTIAL') which the schema does not provide as an enum. It also clarifies that 'notes' is optional and that dispatch_id comes from ledger_log_dispatch.

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

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

The description opens with a specific verb and resource: 'Attach a verification verdict to a previously logged dispatch.' It clearly distinguishes this from siblings like ledger_log_dispatch (which logs the initial dispatch) and ledger_log_approach (which logs an approach). The purpose is unambiguous.

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

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

The description explicitly states when to use the tool: 'Use this after independently verifying a subagent's work.' It also references ledger_log_dispatch as the source of dispatch_id, establishing a clear prerequisite. It does not name alternative tools or explicit when-not scenarios, but the usage context is clear enough to avoid confusion with siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context: actions grouped by category, dispatches show resolved verdict or PENDING, and a 'no entries' message for empty windows. No contradictions exist.

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 appropriately sized and front-loaded with the core purpose. It then provides digestible details on content, parameters, and return value, with every sentence adding value.

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

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

Given the tool's simplicity (one parameter, no nested objects, read-only), the description fully covers behavior, output format, and edge cases. The presence of an output schema is noted, and the description's return explanation is sufficient.

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

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

The schema only provides the type and default for since_hours, with no description. The description explicitly explains that it is 'How many hours back to include' and states the default, fully compensating for the schema's lack of documentation.

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

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

The description clearly states the tool generates a markdown report of actions and dispatches within a time window, with explicit grouping and verdict details. This clearly distinguishes it from sibling tools that log actions, dispatches, verdicts, or provide stats.

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 states it is 'useful for a human-readable audit summary', which clearly conveys when to use it. However, it does not explicitly mention alternatives or when not to use it, though sibling tool names imply other purposes like logging or stats.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context by explaining the aggregation scope (actions and dispatches over N days) and the exact return structure, which goes beyond what annotations provide.

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

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

The description is concise and well-structured, with clear 'Args' and 'Returns' sections. It front-loads the primary purpose and then delivers essential parameter and return information without any filler words.

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

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

The description is complete for a read-only aggregation tool: it specifies the parameter, default value, and full return dictionary with keys and types. The presence of an output schema and clear annotations further round out the context, making the tool self-sufficient.

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

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

The schema parameter 'days' has no description in the schema, but the tool description fully compensates by stating 'How many days back to include. Defaults to 7.' This adds clear semantic meaning and default behavior beyond the bare schema definition.

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: 'Aggregate statistics over actions and dispatches from the last N days.' This is a specific verb+resource combination that clearly distinguishes it from sibling logging tools like ledger_log_action or ledger_log_dispatch, which are write operations.

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

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

The description implies the tool is for reading summary statistics rather than logging individual actions, providing clear context for when it would be used. It does not explicitly mention alternatives or exclusions, but the contrast with sibling tools is evident from the tool's aggregating purpose.

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, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the exact return fields, the formula for retry_count (dispatch_count - 1 floored at 0), and the threshold for over_retry_limit (>= 2). This specifies the tool's semantics without contradicting 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 compact and well-structured with separate sections for Args and Returns. Every line serves a purpose: the first line states the function, the second provides usage context, and the return block details the output. No fluff 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?

The description fully specifies the tool's behavior, return values with types and comments, and the exact context for use. Since there is no separate output schema, the 'Returns' section compensates by documenting all four fields and their meanings. The tool is simple (one param, no nested objects) and the description covers all necessary aspects.

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

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

Schema coverage is 0% in the input schema (task has only type/title). The description compensates fully: 'task (str): The exact task string used with ledger_log_dispatch.' This adds crucial semantic meaning—that the string must match previously logged dispatches—which the schema alone could not convey.

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 'Look up dispatch/retry/verdict status for a given task string,' which is a specific verb+resource phrase. It clearly distinguishes from sibling tools like ledger_log_dispatch (which logs) and ledger_stats (which aggregates). The additional 'Use this BEFORE dispatching a subagent' context further specifies its role.

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

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

Explicitly states when to use: 'Use this BEFORE dispatching a subagent to check whether the same task has already been retried too many times (budget enforcement).' It also references ledger_log_dispatch for task string consistency. However, it does not enumerate when not to use or alternative tools, but the context is clear enough.

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