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

With no annotations, the description carries full burden and does well by disclosing key behaviors: immediate issue creation, background AI process, codebase analysis respecting .gitignore, and return of issue URL/number. It lacks details on permissions, rate limits, or error handling, but provides substantial operational 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 well-structured with bullet points and clear sections, front-loaded with the main purpose. Every sentence adds value, such as explaining the process steps and codebase modes, without 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 5 parameters with 0% schema coverage and an output schema (which handles return values), the description is mostly complete. It covers the tool's process and key parameter semantics but misses some parameter details and behavioral aspects like error cases, making it slightly incomplete for full context.

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

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

Schema description coverage is 0%, so the description must compensate. It explains codebase_reasoning modes in detail (full, lsp, file_structure, none), adding meaning beyond the schema. However, it doesn't clarify title, detailed_description, debug, or disable_search_grounding parameters, leaving some gaps.

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

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

The description clearly states the tool creates a GitHub issue with an implementation plan, specifying it's for GitHub issues and distinguishes from siblings like get_workplan (retrieval) and revise_workplan (modification). The verb 'creates' and resource 'GitHub issue' are specific and unambiguous.

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

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

The description implies usage when needing a detailed implementation plan for a codebase, with context on codebase reasoning modes for different scenarios. However, it doesn't explicitly state when to use this versus alternatives like curate_context or judge_workplan, or any prerequisites for GitHub access.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it analyzes codebase structure, creates a whitelist file, reduces token usage, and improves AI focus. However, it lacks details on potential side effects (e.g., file overwriting), error handling, or performance characteristics like rate limits, leaving some gaps for a tool with significant impact.

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

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

The description is well-structured and front-loaded with the core purpose, followed by a bulleted list of steps and benefits. It's appropriately sized for a complex tool, though the example section could be slightly trimmed without losing clarity. Every sentence contributes to understanding, with minimal redundancy.

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

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

Given the tool's complexity (6 parameters, no annotations) and the presence of an output schema (which handles return values), the description is mostly complete. It explains the tool's role, benefits, and output format (.yellhorncontext file). However, it lacks details on parameter interactions or edge cases, which could aid in more robust usage, leaving room for slight improvement.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions analyzing 'codebase structure' and 'the task you want to accomplish,' which loosely relates to parameters like user_task and codebase_reasoning, but doesn't explain specific semantics (e.g., what user_task entails or how ignore_file_path works). The example .yellhorncontext file adds some context but doesn't directly clarify parameters, resulting in marginal value over the schema.

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

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

The description explicitly states the tool's purpose: 'Analyzes the codebase and creates a .yellhorncontext file listing directories to be included in AI context.' It uses specific verbs ('analyzes,' 'creates') and identifies the resource (codebase, .yellhorncontext file), clearly distinguishing it from sibling tools like create_workplan or judge_workplan, which focus on different aspects of the workflow.

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 this tool: 'This tool helps optimize AI context' and 'Subsequent workplan/judgement calls will only include files from these directories.' It implicitly distinguishes it from siblings by highlighting its role in context curation before other steps, though it doesn't explicitly name alternatives, the context makes the workflow 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a retrieval operation, implying read-only behavior, but doesn't cover critical aspects like authentication requirements, rate limits, error handling (e.g., if the issue doesn't exist), or response format. The mention of 'GitHub issue body' adds some context, but overall, behavioral traits are minimally described for a tool with no annotation coverage.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action ('retrieves') and resource, making it easy to parse. Every part of the sentence adds value, such as specifying 'GitHub issue body,' and there's 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 low complexity (one parameter) and the presence of an output schema (which likely covers return values), the description is somewhat complete but has gaps. It adequately explains what the tool does but lacks usage guidelines, behavioral details (like error cases), and doesn't fully compensate for the 0% schema coverage. For a simple retrieval tool, it's minimally viable but could be more informative.

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 by specifying that the 'issue_number' parameter corresponds to a GitHub issue, which clarifies its purpose beyond the schema's generic title. However, with 0% schema description coverage and only one parameter, the baseline is 3, as the schema lacks descriptions but the description provides some compensation. It doesn't detail format constraints (e.g., numeric string) or examples, leaving gaps.

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

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

The description clearly states the verb ('retrieves') and resource ('workplan content'), specifying it's the GitHub issue body for a given issue number. It distinguishes from siblings like create_workplan or revise_workplan by focusing on retrieval rather than creation or modification. However, it doesn't explicitly differentiate from other read operations like curate_context or judge_workplan, which may also involve reading workplan data.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing issue), exclusions (e.g., not for creating or editing), or comparisons to siblings like curate_context or judge_workplan, which might also access workplan content. Usage is implied by the verb 'retrieves,' but no explicit context or alternatives are stated.

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

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

With no annotations provided, the description carries the full burden and does so well. It discloses key behavioral traits: the process is asynchronous, creates a sub-issue, launches a background AI analysis, and updates the sub-issue upon completion. It also details what the judgement evaluates (e.g., workplan adherence, code quality) and the immediate return of a sub-issue URL, covering most operational aspects.

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, starting with the core purpose. Each sentence adds value: the bullet points clarify steps and evaluation criteria, and the final sentence states the return. There is no wasted text, making it efficient and well-structured for quick understanding.

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 (asynchronous AI process, 8 parameters) and no annotations, the description is largely complete, covering purpose, behavior, and output. It mentions an output schema exists, so return values need not be detailed. However, it could improve by addressing parameter specifics or error handling, but it's sufficient for effective tool 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 description coverage is 0%, so the description must compensate. It adds meaning by explaining the types of comparisons supported (branches, commits, PRs), which relates to parameters like base_ref and head_ref. However, it does not detail other parameters (e.g., codebase_reasoning, debug), leaving gaps. The baseline is lowered due to incomplete coverage of the 8 parameters.

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

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

The description clearly states the tool's purpose: 'Triggers an asynchronous code judgement comparing two git refs against a workplan.' It specifies the verb ('triggers'), resource ('code judgement'), and scope ('against a workplan'), distinguishing it from sibling tools like create_workplan or revise_workplan, which focus on workplan creation or modification rather than evaluation.

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

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

The description provides clear context for when to use this tool: for comparing code changes (branches, commits, PRs) against a workplan. It does not explicitly mention when not to use it or name alternatives among siblings (e.g., get_workplan for retrieval), but the focus on judgement implies it's for evaluation scenarios, offering adequate guidance.

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

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

With no annotations, the description carries full burden and provides good behavioral context: it describes a multi-step process (fetch, AI revision, update), mentions background execution, specifies AI uses same analysis mode/model as original, and notes immediate return of issue URL/number. It doesn't cover permissions, rate limits, or error handling, but adds substantial value beyond basic purpose.

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

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

The description is well-structured and front-loaded: the first sentence states the purpose, followed by a bulleted list of steps and additional details. Every sentence adds value—no repetition or waste—making it efficient and easy to parse.

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

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

Given 5 parameters with 0% schema coverage, no annotations, and an output schema (which handles return values), the description does well by explaining the core process and key parameters. It could improve by covering optional parameters and more behavioral aspects like error cases, but it's largely complete for a mutation tool with output 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 description coverage is 0%, so the description must compensate. It implicitly explains 'issue_number' (fetches from GitHub issue) and 'revision_instructions' (basis for AI revision), covering the two required parameters. However, it doesn't address optional parameters like 'codebase_reasoning' or 'debug', leaving some gaps in parameter understanding.

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

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

The description clearly states the tool's purpose: 'Updates an existing workplan based on revision instructions.' It specifies the verb ('Updates'), resource ('existing workplan'), and distinguishes from siblings like 'create_workplan' (creates new) and 'get_workplan' (reads only). The three-step breakdown further clarifies the scope.

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

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

Usage is implied by mentioning it updates an existing workplan from a GitHub issue, suggesting it's for revisions after creation. However, it lacks explicit guidance on when to use this vs. alternatives like 'create_workplan' for new workplans or 'judge_workplan' for evaluation, and doesn't mention prerequisites or exclusions.

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