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

No annotations provided, but description clearly states read-only behavior and lists return values. Adequate for a safe, non-destructive analysis tool; does not mention performance or auth, but not critical for this kind of tool.

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

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

Two concise sentences with no fluff. Front-loaded with verb and resource. 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?

For a zero-parameter tool with an output schema, the description fully covers the tool's purpose, behavior, and return contents. No gaps.

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

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

No parameters exist, so schema coverage is 100%. The description adds context about the analysis scope and output, which is valuable beyond the empty 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 uses a specific verb ('Analyse') and resource ('existing Taskwarrior tasks') and clearly differentiates from siblings like 'analyze_taxonomy_file' or 'get_schema_info'. It states the output: field occurrence ratios, enum values, required fields, projects, tags, and UDAs.

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 read-only nature and mentions inference purpose. Implicitly suggests when to use: when schema inference from existing tasks is needed. Lacks explicit exclusions or alternatives, but context from sibling tool names provides some differentiation.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It states read-only, which is a helpful safety trait, but lacks details on error conditions, authentication, or side effects. The phrase 'when possible' adds some nuance but is insufficient.

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

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

The description is brief and front-loaded with the main action in the first sentence. 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 the tool's simplicity (one parameter, output schema exists), the description covers core purpose and behavior. However, it omits prerequisites (e.g., setting taxonomy path first) and error handling, leaving gaps 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?

Schema description coverage is 0%, requiring the description to compensate. It clarifies that the path should point to a taxonomy Markdown file, adding meaning beyond the schema. However, it does not specify path format, restrictions, or examples.

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

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

The description clearly states the tool's action (parse) and resource (taxonomy Markdown file), and lists specific extracted semantics (fields, descriptions, etc.). It distinguishes itself from sibling tools like set_taxonomy_path and analyze_existing_tasks_for_schema.

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 explicit guidance on when to use this tool versus alternatives. The read-only hint is the only contextual clue, but no when-not-to-use or prerequisite information 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?

With no annotations provided, the description fully discloses key behavioral traits: annotations are appended (not replacing others), automatically timestamped, support dry_run, and require CONTRIBUTOR role. No contradictory information.

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 5 sentences, front-loaded with the core purpose, followed by behavioral details, usage guidance, and constraints. 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?

The description covers all essential aspects: purpose, behavior (append, not replace, timestamp), usage guidance (when/not), dry_run, role requirement, and distinction from sibling modify_task. With an output schema present, return values need not be explained.

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%, but the description adds meaning beyond the schema: it explains that annotations are appended with automatic timestamps, and mentions dry_run. However, it does not explicitly describe the uuid parameter or the format of the annotation string.

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 'Append a timestamped annotation to a task', specifying the verb (append), resource (task), and the nature (timestamped annotation). It distinguishes from modify_task by noting that annotations are for narrative context, not structured fields.

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 (for narrative context, URLs, reference links) and when not to (for structured fields, use modify_task). It also mentions the dry_run option for preview and the CONTRIBUTOR role requirement.

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 non-atomicity (no rollback), sequential creation, rate-limit behavior, partial results, dry_run preview behavior. No annotations provided, so description bears full burden and does so thoroughly.

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

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

Well-structured with clear sections, but slightly lengthy. Every sentence adds value; could be slightly more concise but 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?

Covers all critical aspects: purpose, usage guidance, behavioral details, parameter specifics, prerequisite (get_schema_info), and role requirement. No gaps given 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?

Schema coverage is 0%, but description compensates fully by detailing each field in the 'tasks' array: description, project, priority, tags, due, extra_fields. Also explains dry_run.

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 multiple tasks in a single call with per-task result reporting. It distinguishes from siblings like create_task and create_subtask.

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 prefer this over create_task and when to use create_subtask instead. Also mentions required GENERATOR role and recommends calling get_schema_info first.

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

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

With no annotations provided, the description fully discloses behavioral traits: non-atomic sequential modification, failure handling (single task failure doesn't stop batch), dry_run preview workflow, and confirm_token requirement for high-impact changes.

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 well-structured, front-loaded with purpose, and uses efficient sentences. 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 no annotations and an output schema present, the description covers all necessary context: behavior, parameters, usage patterns, auth requirements, and error handling.

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

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

Schema coverage is 0%, so description compensates well. It explains filters (Taskwarrior syntax), fields (field/value pairs with special tags notation), dry_run, and confirm_token. Could be slightly more precise on field format, but adds meaningful context 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 it modifies all tasks matching a filter in a single call. It distinguishes from sibling tools like 'modify_task' by specifying batch vs single-task operation.

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 tells when to use this tool ('Use modify_task for targeted single-task changes'), when not, and provides workflow guidance (dry_run first, confirm_token for high-impact changes). Also mentions required role: MANAGER.

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 labels the operation as 'Destructive' and notes potential confirmation requirements. However, it lacks details on irreversibility or effects on related tasks. With no annotations, the description provides minimal but useful 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 extremely concise, using a single line for purpose and a clear list for arguments. 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?

The description covers the basic purpose and two parameters, but fails to document the 'confirm_token' parameter or describe the return value (despite an output schema existing). It is adequate for a simple tool but not fully complete.

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

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

Schema coverage is 0%, so the description must explain parameters. It describes 'uuid' and 'dry_run' but omits 'confirm_token' entirely. Only 2 out of 3 parameters are explained, leaving a 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 'Mark a task as done (completed)', specifying the action and resource. This distinguishes it from related tools like create_task, delete_task, or modify_task.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., modify_task or start_task). There is no mention of prerequisites or when not to use it.

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 the subtask will have a 'depends' field set to parent UUID, but no other behavioral traits are mentioned. With no annotations, the description should include more about error handling or idempotency.

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?

Structured with an 'Args:' block, front-loaded with a clear one-line purpose. A bit wordy but each 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?

Given 8 parameters and complexity, the description covers core functionality and suggests a prerequisite action. However, it omits 'dry_run' and does not explain success/error behavior. Output schema exists, reducing the need for return value documentation.

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 most parameters (parent_uuid, description, project, priority, tags, due, extra_fields) but entirely omits the 'dry_run' parameter. Schema coverage is 0%, so the description adds value but is incomplete.

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 'Create a subtask with depends: linking to a parent task.' The verb and resource are specific. However, it could better distinguish from 'create_task' as sibling tools include both.

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?

Includes a directive to 'Call get_schema_info first to see required and available fields.' But lacks explicit comparison to alternatives or 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?

With no annotations, the description should disclose behavioral details like error handling, idempotency, and side effects. It mentions 'schema validation' but does not explain what happens on validation failure or if the task is actually created. The presence of a 'dry_run' parameter in the schema hints at preview capability, but the description omits this parameter entirely, leaving ambiguity.

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 concise with a clear 'Args' section front-loading purpose and parameter details. It avoids unnecessary repetition but could be slightly more compact by merging some examples.

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 no schema coverage, the description covers most parameters adequately and includes a usage prerequisite. However, it lacks details on the return format (though output schema exists) and does not elaborate on validation behavior or what constitutes a successful creation. The omission of 'dry_run' is a notable gap.

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

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

Given 0% schema coverage, the description adds meaning for most parameters: 'description' (imperative, actionable), 'project' (dot-notation), 'priority' (H/M/L), 'tags' (list), 'due' (ISO or relative), and 'extra_fields' (UDA fields). However, it fails to describe the 'dry_run' parameter, which is present in the schema but undocumented in the 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 'Create a new Taskwarrior task with schema validation', specifying the action and resource. While it distinguishes from siblings like 'delete_task' or 'modify_task' by name, it does not explicitly differentiate from similar creation tools like 'batch_create_tasks' or 'create_subtask'.

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 advises to 'Call get_schema_info first to see required and available fields', providing a helpful prerequisite. However, it does not specify when to use this tool versus alternatives, nor does it state conditions under which it should not be used.

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 the operation as 'Destructive' and notes potential confirmation, which is helpful with no annotations. However, lacks details on side effects (e.g., subtask behavior, permanent deletion) and does not explain the confirm_token parameter.

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?

Extremely concise: 4 short lines plus parameter docs. Every sentence serves a purpose, no redundancy. The main action 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?

Covers essential behavior and parameter semantics partially, but given the presence of an output schema (not shown), the description could be more complete on return values and error conditions. Missing documentation on confirm_token is a gap.

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

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

Documents uuid and dry_run with clear descriptions, adding value beyond schema. However, fails to mention confirm_token, which is a third parameter in the schema. Schema coverage is 0%, so description should cover all parameters; missing one reduces 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?

Clearly states 'Delete a task from Taskwarrior' with a specific verb and resource. The note 'Prefer completing over deleting' explicitly distinguishes it from the sibling complete_task.

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

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

Explicitly advises preferring completion over deletion, giving a clear when-not-to-use. Also mentions potential confirmation requirement, but does not list other alternatives like archiving or all 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?

With no annotations, the description serves as the sole source for behavioral traits. It explicitly states 'Read-only: returns a preview string only; no files are created or modified', clearly communicating the tool's non-destructive nature.

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

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

The description is well-structured with front-loaded purpose and read-only guarantee, followed by parameter details. It is mostly concise, though could slightly tighten wording (e.g., 'Call save_initial_schema only after the user approves' is clear but slightly redundant with the read-only note).

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 (context signals indicate 'Has output schema: true'), the description appropriately focuses on prerequisites, behavior, and parameter guidance. It mentions the return type 'preview string', which aligns with the output schema expectation.

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

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

Despite 0% schema description coverage, the description adds comprehensive meaning to all three parameters: taxonomy_path (absolute path or infer from tasks), project_dir (scope subdirectory), and schema_name (name in meta block), fully compensating for the schema's lack of 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 'Generate a reviewable schema TOML preview without writing any files' using a specific verb and resource, and distinguishes it from sibling tool 'save_initial_schema' by noting it should be called only after user approval.

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: after running 'analyze_existing_tasks_for_schema' or 'analyze_taxonomy_file', and before calling 'save_initial_schema'. It also explains the preview combines task analysis with optional taxonomy.

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

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

With no annotations provided, the description fully discloses the tool's read-only nature, its return value (name and filter expression or no context), and its effect on other tools. This is comprehensive and adds significant value beyond the structured data.

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 clear and informative, but it is slightly verbose with repeated emphasis on 'automatically'. It could be tightened without losing meaning, but overall it is well-structured and front-loaded.

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

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

Given the zero parameters and presence of an output schema, the description covers all necessary aspects: purpose, return value, side effects, and relationship to sibling tools. It is fully complete for an agent to understand usage.

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

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

The tool has no parameters, so the description does not need to add parameter detail. The description is consistent with the input schema (empty) and the baseline score of 4 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 uses a specific verb 'Show' and resource 'currently active Taskwarrior context filter', clearly distinguishing it from sibling tools that operate on tasks directly. It precisely conveys the tool's function without ambiguity.

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 read-only nature and the tool's role in narrowing output of other tools (list_tasks, get_task_report). It implies when to use it (when context info is needed) but does not explicitly state alternatives or when not to use it, which would improve clarity.

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. It explicitly states 'without mutating tasks or config', which is a key behavioral guarantee. The output schema exists, so return value details are not required, but the description could hint at what the 'onboarding state' includes.

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

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

Two sentences, front-loaded with purpose and usage. No unnecessary words.

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

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

While the description is clear and has an output schema, it lacks parameter explanation (only one parameter). For a simple inspection tool with many siblings, it is minimally adequate but not fully complete.

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

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

The description does not mention the sole parameter 'project_dir' at all. With 0% schema coverage, the description should explain its purpose or usage, but it fails to do so.

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 'Inspect' and the resource 'first-run onboarding state', and it distinguishes itself from sibling tools that involve mutation or analysis by emphasizing non-mutating behavior.

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: 'Use this before task creation/modification if the active schema may be the bundled minimal default'. This implies when to use and when not, but does not explicitly name 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?

Discloses it is read-only and returns a flat list including subproject hierarchies. No annotations provided, so description adequately covers behavioral traits. No mention of side effects, but none 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?

Three concise sentences with no waste. The most important information is front-loaded: 'List all project names.' Every sentence earns its place.

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

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

Tool is simple with no parameters and an output schema. Description covers purpose, usage, behavior (read-only), and output format, making it complete for this tool.

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

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

No parameters; schema coverage is 100% by default. Description adds value by explaining the return format and usage, which is appropriate for a parameterless tool.

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 lists all project names, including subproject hierarchies. The verb 'List' and resource 'project names' are specific. It distinguishes from sibling tools like create_task or list_tasks by being a read-only list of projects.

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 create_task or filter queries to confirm project name spelling.' This provides clear context, though it does not explicitly mention when not to use it.

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 what the tool returns (mode, role, schema, callable/blocked groups with reason codes). No annotations needed; description fully covers behavior.

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

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

Three sentences, front-loaded with purpose, then usage advice, then detail. 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?

With zero parameters and an output schema indicated, the description explains return values adequately. Sufficient for a first-use 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?

No parameters, but description adds meaning beyond the empty schema by explaining the response contents.

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

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

The description clearly states the tool returns the server's current mode, role, schema, and callable tool groups. It uses specific nouns and a clear verb, and distinguishes from sibling tools as an introspection tool.

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 recommends calling this tool first to understand server capabilities. Provides clear guidance without needing 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?

No annotations are provided, so the description carries full responsibility. It describes the return content but does not disclose any behavioral traits such as authentication needs, caching, or side effects. For a read-only informational tool, this is adequate but not comprehensive.

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

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

The description is three sentences, each serving a distinct purpose: stating the tool's function, listing output components, and providing usage guidance. It is concise, front-loaded, and contains no unnecessary words.

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

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

Given the tool's simplicity (no parameters, no annotations, and an output schema exists), the description comprehensively covers purpose, output, and usage context. There are no apparent 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 tool has zero parameters, and the input schema is empty. Schema coverage is 100%. Per guidelines, a baseline of 4 applies. The description does not need to add parameter semantics.

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

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

The description clearly states the tool's purpose: 'Get the active task schema definition.' It specifies what it returns (field definitions, required fields, allowed values, and conditional requirements). This distinguishes it from sibling mutation and analysis 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 explicitly says 'Use this to understand what fields are available before creating or modifying tasks,' providing clear context for when to use it. It does not mention when not to use it or alternatives, but the guidance is sufficient.

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

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

No annotations are provided, but the description clearly marks the tool as 'Read-only' and states it returns every tag appearing on at least one task. This sufficiently discloses behavioral traits (no side effects, scope of results) beyond what the schema indicates.

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, each serving a distinct purpose: stating the action, specifying scope, and providing usage advice. It is front-loaded with the primary purpose and contains no superfluous text.

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

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

For a zero-parameter tool with an output schema, the description is complete: it explains what is returned (tags), when to use it, and that it is read-only. It does not mention ordering or performance, but these are not critical for effective usage.

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

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

The tool has zero parameters, so the baseline is 4. The description does not add parameter information (none needed), and the schema coverage is complete. No points deducted.

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 'List all tags used across the Taskwarrior database' with a specific verb and resource. It distinguishes itself from sibling list tools by focusing solely on tags and providing usage context (e.g., before create_task), 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?

The description explicitly advises using this tool before create_task, modify_task, or filter queries to confirm tag spelling. This provides clear guidance on when to use it, though it lacks explicit 'when not to use' or alternative 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?

Declares read-only behavior and describes return format (full task JSON including UDA fields and annotations). No annotations exist, so description carries full burden; it lacks error handling details but covers essential behavioral traits for a simple read operation.

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

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

Three short paragraphs, each with a distinct purpose: purpose, return details, usage comparison. No redundant sentences. Efficiently structured.

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 (1 required param, no annotations, no output schema shown), the description fully covers what the agent needs to know: what it does, how to identify the task, and when to use it over alternatives.

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?

Single parameter 'uuid' has 0% schema description coverage. Description compensates by explaining why UUID is critical (local IDs change) and that it returns complete data. Adds meaningful context beyond schema type.

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 'Get a single task by UUID and return all its fields.' Specifies verb (get), resource (task), and scope (by UUID, all fields). Distinguishes from sibling list_tasks by 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?

Explicit guidance: when to use this tool vs list_tasks ('Use this over list_tasks when you have the UUID and need complete field data'). Also warns about numerical IDs vs UUID, preventing misuse.

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?

Declares 'Read-only' upfront, clearly indicating no side effects. No annotations to contradict; description carries full burden for behavioral disclosure.

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 three-sentence structure: purpose, list of examples, filters explanation, and usage guidance. No unnecessary words; well-organized.

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?

Completely covers tool's function, parameters, usage context, and output nature. With output schema present, no need to detail return values. For a read-only tool, all essential aspects are addressed.

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

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

Despite 0% schema description coverage, description adds rich meaning: report_name explained with examples, filters described as Taskwarrior syntax with example usage. Greatly enhances 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?

Clearly states 'Run a named Taskwarrior report and return its output. Read-only.' with specific verb and resource. Lists built-in report names and custom support, distinguishing from sibling list_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?

Explicitly states when to use ('formatted report view or urgency ordering is more useful') and when to use sibling ('Use list_tasks for raw JSON output'). Provides guidance on filters syntax.

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 absent, but description fully discloses read-only behavior, return content (state, tags, duration), and graceful handling of missing installation. No side effects implied; adequate transparency.

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

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

Four concise, well-structured sentences. Every sentence adds value: purpose, return values, error handling, alternatives. 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 no parameters, existing output schema, and sibling tools, description fully covers behavior, output, edge case, and alternatives. No gaps.

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

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

No parameters, schema coverage 100%. Description adds no param info (none needed) but exceeds baseline by clarifying zero-parameter nature implicitly. Baseline 4 applies.

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 checks if Timewarrior is tracking time (specific verb+resource), distinguishes itself from get_time_summary (historical aggregates) and start_task/stop_task (control). Read-only nature is explicit.

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 alternatives: 'Use get_time_summary for historical aggregates. Use start_task / stop_task to control tracking via Taskwarrior hooks.' Also covers edge case (Timewarrior not installed) with non-error message.

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?

Despite no annotations, the description fully discloses read-only nature, return behavior (empty results for missing install or no tracked time), and all accepted period syntax.

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?

Every sentence adds value: primary purpose, read-only note, special return behavior, detailed period syntax, and cross-reference to sibling. 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 one optional parameter and an output schema, the description covers behavior, parameter formats, edge cases (missing install), and tool alternatives, leaving no gaps.

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

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

Schema coverage is 0%, but the description thoroughly explains the 'period' parameter with examples and default value, far exceeding the schema's minimal info.

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 verb 'get' and resource 'time-tracking summary' are specific and clear. It distinguishes from sibling get_time_status by mentioning it checks if tracking is active.

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 it's read-only, explains that empty results are not errors (handles missing installation or no tracked time), and provides multiple valid period formats. Also directs when to use get_time_status.

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?

States 'Read-only' and details the output fields (name, file path, version, description) and their origin from the schema's [meta] block, providing full behavioral transparency despite no 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 concise sentences that front-load purpose, provide usage guidance, and detail output—every sentence is valuable.

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 covers purpose, usage, and return values for a zero-parameter tool with an output schema, leaving no gaps.

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

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

No parameters exist, so schema coverage is 100%. The description adds context about what is returned, which is acceptable for a parameterless tool.

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: listing bundled preset schemas, and provides examples (minimal, gtd, kanban, scrum) which distinguishes it 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?

Explicitly instructs to use this before calling use_preset_schema, giving clear context and preventing guessing of preset names.

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

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

Declares read-only and returns JSON array. Lacks mention of any result limits, pagination, or ordering, but given no annotations, it covers core behavior adequately.

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

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

Well-structured: purpose sentence, output type, filter syntax examples, sibling tool recommendations. No redundant 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?

Has output schema. Covers filtering and alternatives. Minor gaps: no mention of sort order or result limits, but sufficient for a list operation.

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

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

Despite 0% schema coverage, the description extensively documents the single 'filters' parameter with syntax examples, combining rules, and default behavior.

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

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

The description clearly states 'List and filter Taskwarrior tasks' and specifies read-only nature. It distinguishes from siblings like get_task (UUID lookup) and search_tasks (field-specific free-text).

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 alternatives: 'Prefer get_task for UUID... Prefer search_tasks for free-text... Use get_task_report for named reports.' Also explains default filter behavior.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It does not mention idempotency, error handling, side effects, or whether changes are reversible. The dry_run parameter is not explained in the description, leaving the agent unaware of its effect.

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, using an args list with examples. Every sentence adds value, though the dry_run parameter could be mentioned briefly without adding much 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?

The tool has an output schema, so return values need not be explained. However, as a mutation tool, it should disclose behavioral aspects like permissions, reversibility, and dry_run behavior. The description is adequate for basic usage but lacks completeness for safe agent 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 description coverage is 0%, so the description must compensate. It adds meaning for the 'fields' parameter with examples of field:value pairs and tag modifications. However, 'uuid' is only briefly mentioned as 'Task UUID' and 'dry_run' is completely omitted, providing incomplete 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 the action: 'Modify fields on an existing task.' The verb 'Modify' and resource 'fields on an existing task' are specific. This distinguishes it from siblings like create_task, delete_task, and bulk_modify, which handle different 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?

No guidance is provided on when to use this tool versus alternatives such as bulk_modify for multiple tasks or annotate_task for specific fields. There is no mention of prerequisites, limitations, or when not to use it.

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

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

With no annotations, the description fully documents behavior: declares read-only nature twice, notes that no config/schema/task data is written, and describes the parameter's effect. It does not mention rate limits or idempotency, but given the read-only, side-effect-free nature, this is sufficient. 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?

At ~150 words, the description is longer than ideal but well-structured. It opens with the core purpose, immediately states read-only nature, then provides usage order and alternatives, finally adding parameter detail. Every sentence adds value, though some repetition of 'read-only' occurs.

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 (so return format is documented separately), and the tool has 33 siblings, the description covers the critical context: when to call it, what it returns (menu), and what to do next. No gaps remain for an agent to misuse the 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?

The single parameter 'project_dir' has 0% schema description coverage, but the description adds rich semantics: 'optional path scoping task analysis to a project subdirectory. Pass empty string (default) to analyse all tasks.' This clarifies behavior far beyond the bare schema.

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

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

The description clearly states the tool's purpose: returning structured onboarding choices. It specifies what the tool does not do (read-only, no config writing) and distinguishes from sibling tools by framing the output as a menu for subsequent step selection. The verb 'propose' plus structured object is specific and unambiguous.

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

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

Explicit guidance is provided: 'Call after get_initialization_status confirms onboarding is required.' It also lists concrete next steps (analyze_existing_tasks_for_schema, etc.) and tells the agent to choose one. This is clear when-to-use and what-to-do-next advice.

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?

Descriptors list what gets reloaded (config, schema, rate limiter, etc.), adding behavioral context beyond the lack of annotations. Could mention potential side effects but is sufficient.

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

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

Four sentences, each earning its place: purpose, usage, reload list, and auto-reload exemption. Front-loaded with key information.

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

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

Complete coverage for a simple tool: purpose, usage, behavior, and relationship to siblings. Output schema exists but is 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?

No parameters exist; schema coverage is 100% trivially. Description does not need to add parameter info, and it provides ample context for a parameterless tool.

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: reread config.toml and refresh runtime state. It distinguishes from sibling tools by noting that other tools auto-reload, making this tool rarely needed.

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 hand-editing config.toml) and when not to use (other tools auto-reload), providing clear guidance for the agent.

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. It discloses that writes schema/config files and does not mutate tasks, and explains role implications. However, it omits details on error behavior, file overwrite behavior, and default paths, leaving gaps in transparency.

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

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

The description is concise (four sentences) with a clear front-loaded structure: main action first, then scope limitation, then prerequisite, then parameter guidance. Every sentence 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?

Despite having 6 parameters and no schema descriptions, the description only addresses the role parameter. It does not explain other parameters, their defaults, or return values (output schema exists but not described). This is incomplete for a tool of this 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 0%. Only the role parameter is explained in detail; the other five parameters (schema_toml, taxonomy_path, output_path, overwrite, update_config) receive no description, failing to add meaning beyond the schema's limited property names.

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 persists an approved generated schema and optionally updates config.toml. It distinguishes itself from siblings by referencing the prerequisite tool generate_initial_schema_preview and stating it does not mutate Taskwarrior tasks, providing 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?

Explicitly instructs to call generate_initial_schema_preview first and show summary before saving. Also provides detailed guidance on the role parameter, including allowed values and consequences of omission, establishing clear when-to-use 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?

No annotations provided, so description carries full burden. It states 'Read-only', matching behavior (case-insensitive substring), field defaults and possible values (description, project, tags, any UDA name), and returns tasks as JSON. No contradictions.

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

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

Description is about 6 sentences, starting with purpose, then behavior, then details. No fluff. Well-structured and efficient.

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

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

For a 2-param search tool with no annotations and output schema, description covers param semantics, behavior, and usage guidance. Missing minor details like pagination or empty result behavior, but overall adequate.

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

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

Schema coverage is 0%, so description adds essential meaning. It explains 'query' is the search string, 'field' defaults to 'description' and lists valid values (project, tags, UDA names), and notes field must exist in schema or be built-in.

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 searches tasks by matching a query against a specific field. It specifies the verb 'search' and the resource 'tasks', and explains matching is case-insensitive substring. It distinguishes from list_tasks by mentioning filter syntax vs free-text 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 states when to use this tool: for free-text search when filter syntax is insufficient or when searching across a UDA field. It advises using list_tasks for structured queries and explains field defaults and valid values.

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

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

With no annotations, the description fully discloses behavior: it writes to config.toml, triggers in-process reload (ADR 19), does not mutate tasks, and returns 'code="dry_run"' for dry runs (ADR 14). Authorization context (CONTRIBUTOR level) is provided.

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, starting with the main purpose, then detailing parameters, dry-run usage, side effects, and authorization. It is slightly verbose but each sentence adds value, and it avoids 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 and the presence of an output schema, the description covers all necessary aspects: purpose, parameter distinction, validation mode, side effects (config update, reload, no task mutation), authorization, and relevant ADRs. It is complete for an agent to use correctly.

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

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

Schema description coverage is 0%, but the description explains each parameter: 'schema_name' is a bundled preset, 'schema_path' is an absolute path to TOML, and 'dry_run' is a boolean for validation. It adds context like 'such as 'minimal'/'gtd'/'kanban'/'scrum'' and usability tips. It does not detail error handling for missing inputs, but the requirement 'exactly one must be provided' is clear.

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

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

The description clearly states the tool's action: 'Switch the active task schema.' It distinguishes from sibling tools like 'use_preset_schema' by specifying both preset names and custom paths, and explicitly requires exactly one of 'schema_name' or 'schema_path'.

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 usage guidance: exactly one of two parameters must be provided, 'dry_run=true' is recommended for validation, and it mentions the authorization level (CONTRIBUTOR and above). It does not explicitly exclude alternatives like 'use_preset_schema', but the context is sufficient.

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

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

With no annotations provided, the description carries full burden. It discloses that the tool is downgrade-only, takes effect on next restart, includes a structured error for elevation attempts with error_code, explains dry_run behavior (preview without touching config, returns code='dry_run'), and notes that refusal errors trigger regardless of dry_run. This is comprehensive.

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

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

The description is well-structured with clear sections and front-loaded key point ('DOWNGRADE ONLY'). Every sentence adds value, but it is slightly lengthy; however, the detail is justified for behavioral clarity. Minor reduction possible without losing 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 that an output schema exists (though not shown), the description still covers behavior, error scenarios, and dry_run. It addresses edge cases (elevation refusal) and provides comprehensive guidance for a tool with 2 parameters. It feels complete for an agent to use correctly.

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

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

Schema coverage is 0%, so description must explain each parameter. It explains 'target_role' as the desired role with condition (≤ current level), and 'dry_run' as a validation/preview mode with explicit behavior (no config write, returns code='dry_run'). This adds significant meaning beyond schema types.

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 changes the persisted MCP role, explicitly notes it's downgrade only, lists valid roles (CONTRIBUTOR, GENERATOR, MANAGER), and distinguishes from any sibling tools (none are role-related). The specificity of verb and resource is high.

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 when to use (to downgrade role), when not to use (elevation is forbidden with alternative methods for elevation provided: shell command or config edit), and includes a dry_run option for validation. It gives clear guidance on the conditional logic and error handling.

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

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

No annotations provided, so description fully discloses key behaviors: path must exist and be a file, refusal of non-existent or directory targets to prevent silent disable, dry_run validation and preview, return code 'dry_run', and effect on restart.

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 7 sentences, front-loaded with main purpose, each sentence adds value without redundancy. Efficient use of 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 2 parameters, no annotations, and presence of an output schema, the description covers all necessary context: purpose, constraints, access level, effect timing, return behavior. Complete for a config-update 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 0%, but description adds substantial meaning: path must exist and be a regular file; dry_run=true validates and previews without modifying config.toml. This goes well beyond the schema's bare type 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 clearly states the verb (Update) and resource (taxonomy file path persisted in config.toml), and explains the purpose (informs model interpretation of task semantics). It distinguishes from sibling tools like analyze_taxonomy_file which focus on analysis, not configuration.

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 context such as access level (CONTRIBUTOR) and effect timing (next restart). However, lacks explicit when-to-use vs alternatives, though sibling analysis implies uniqueness.

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

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

No annotations provided, so description carries full burden. It discloses behavioral traits: sets start field, affects reports, triggers Timewarrior time tracking with task tags, supports dry_run for preview, and specifies it does not complete or delete.

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, front-loaded with primary purpose, and structured in clear bulleted 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?

Given no annotations but presence of output schema, description covers behavior, prerequisites, mutation behavior, dry run support, and relationships to sibling tools. Complete for effective 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 0%, but description adds context for dry_run parameter (preview without mutation). uuid is not described but is self-explanatory given the tool purpose. Missing details like uuid format or constraints, but overall adequate.

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 verb (mark as active) and resource (task), and distinguishes from siblings like stop_task and complete_task by specifying that it does not complete or delete.

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 (to activate and start time tracking), and when not (does not complete/delete). Names alternatives (stop_task, complete_task) and mentions role requirement (CONTRIBUTOR).

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

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

No annotations provided, but description fully explains effects: clears start field, stops time tracking if Timewarrior installed, supports dry_run for preview. States it does not complete or delete the task.

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?

Six sentences, no wasted words. Front-loaded with main action, then subsidiary details. 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 no annotations and 2 parameters, description covers action, behavior, dependencies, and role. Doesn't describe output schema but one exists, so not required. Missing a bit on parameter 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 0%, so description should compensate. It explains dry_run parameter but not uuid. While uuid is standard, the description could briefly note it uniquely identifies the task.

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 deactivates a task by clearing its start timestamp. Distinguishes from siblings like start_task and complete_task by explaining what it does and does not do.

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 (stop tracking work sessions), pairs with start_task, and alternative complete_task for marking done. Mentions required CONTRIBUTOR role.

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

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

With no annotations provided, the description fully covers behavior: pushes/pulls changes, conflict resolution (server-side, local changes not lost but reordered), and role requirement (MANAGER). It also indicates error conditions and dry_run effects.

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

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

The description is extremely concise—three sentences covering purpose, prerequisites, behavior, and parameter. No unnecessary words, and the most important information appears first.

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, output schema exists), the description covers everything: purpose, prerequisites, behavior, parameter usage, and role requirement. 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 only parameter, dry_run, has 0% schema coverage, but the description fully explains its meaning: 'Supports dry_run=true to check connectivity without transferring data.' This adds essential semantic context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Trigger a sync with the configured TaskChampion sync server.' It uses a specific verb and resource, and distinguishes itself from siblings which are all CRUD or analysis tools, none of which perform sync.

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 prerequisites: 'Requires a TaskChampion sync server configured in .taskrc. Returns an error if no sync server is configured.' It also mentions the dry_run option for checking connectivity, giving clear guidance on when 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?

No annotations are provided, so the description carries full burden. It fully discloses destructive nature, single undo capability, dry_run support, confirm_token requirement, and batch operation caveat.

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 clear paragraphs and each sentence adds value. Slightly verbose but appropriate for the level of detail needed.

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 and presence of an output schema, the description covers all necessary behavioral aspects, parameter semantics, and usage conditions 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?

Despite 0% schema description coverage, the description explains dry_run for preview and confirm_token for server-configurable confirmation, adding significant meaning beyond the schema.

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

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

The description clearly states 'Undo the most recent Taskwarrior operation,' using a specific verb and resource. It distinguishes itself from sibling tools, as no other tool has undo functionality.

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

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

The description explicitly explains when to use the tool (revert last change), includes important limitations (only one level, no redo, not for batch operations), and lists prerequisites (requires MANAGER role).

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

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

With no annotations, the description fully discloses behaviors: default behavior sets schema in config.toml, copy copies the file, refuses overwrite unless specified, and not persisting a role keeps the server in onboarding mode. 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?

Front-loaded with clear purpose, uses structured paragraphs and bullet points. Every sentence adds essential information without redundancy, achieving high information density.

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 critical aspects: default versus copy, overwrite protection, role persistence consequences, and references to other tools. The presence of an output schema means return values need not be described.

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

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

Despite 0% schema coverage, the description adds meaning to key parameters: preset_name, copy, overwrite, role, and output_path (via copy context). However, taxonomy_path and update_config are not explained, 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 wires a preset schema into config.toml, specifying two modes (default and copy). It distinguishes itself from siblings like set_active_schema and list_preset_schemas by its unique action of modifying config.toml.

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 explains when to use copy=true versus default, warns about overwrite behavior, and details the role parameter's effect on onboarding mode. Points to propose_initialization_options for role descriptions, guiding when to use alternatives.

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