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

Annotations already show this is a write (readOnlyHint=false) and non-idempotent. The description adds useful behavioral context beyond annotations: it is a batch operation and item ordering matters because later items can parent to earlier names. It does not disclose failure/rollback behavior, but for a simple creation tool this is reasonable.

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

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

Two sentences, front-loaded with the core action and then the ordering detail. Every sentence adds value with no filler or repetition of schema fields.

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 one-parameter tool with an output schema and a described items schema, the description plus schema is mostly sufficient: it explains batching and parent-name ordering. The only minor gap is that per-item required fields are left open (schema allows additionalProperties), but sibling tools like add_task/add_project can fill that in.

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

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

The schema already covers the items parameter with a description of tasks/projects and parentTaskName usage (100% coverage). The tool description adds little beyond echoing that language, so the baseline of 3 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 states a specific action ('Create many tasks or projects') and resource ('in one OmniJS call'), which clearly distinguishes add_items from the single-item add_task and add_project siblings. It also adds the batching nuance that later items can reference earlier names.

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

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

The description implies the use case: use when you need to create many tasks/projects in one call, particularly with parent relationships. However, it never explicitly names alternatives or says when not to use this tool, leaving the comparison to add_task/add_project implicit.

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

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

Annotations already indicate a non-read-only write operation, lowering the burden. The description adds that the tool can also create an initial task list and place the project in a folder, which is useful side-effect context. It does not cover failure modes or permission requirements, but the annotation coverage provides a baseline.

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?

A single, front-loaded sentence with no filler. It is concise and readable, though the brevity contributes to the lack of detail elsewhere.

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 14 parameters and low schema coverage, one sentence is not enough for an agent to invoke this tool confidently. It covers the essential purpose but omits most parameter semantics and sibling differentiation; the presence of an output schema does not make up for the input-side gaps.

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

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

Schema description coverage is only 29%, and the description only clarifies the folder and initial-task-list aspects. The other 10+ parameters (note, tags, status, due_date, etc.) are left without added meaning, so the description does not compensate for the sparse schema.

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

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

The description states a clear verb ('Create') and resource ('project') with two distinguishing capabilities: optional folder placement and an initial task list. It does not explicitly name sibling tools like create_project_from_outline, but the core object is unambiguous.

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

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

No explicit guidance is given on when to use this tool versus alternatives such as create_project_from_outline or add_task. The optional folder/task-list hint implies some use cases, but there are no exclusions or decision rules to help an agent choose correctly.

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

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

The annotations only indicate this is a write operation in a closed world with no idempotency or destructive guarantee. The description adds no behavioral context beyond the word 'Create': it does not mention duplicate handling, conflicts such as parent versus project, required permissions, or response behavior. No contradiction with annotations is present.

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?

A single front-loaded sentence with no filler. The verb and object appear first, and the optional capabilities follow compactly. Every word earns its place.

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

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

This is a 16-parameter creation tool with a minimal description and no annotation support. Although an output schema exists, the description omits meaningful context such as how to associate a project or parent and which optional fields are mutually exclusive. It is not complete enough for reliable invocation in non-trivial cases.

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

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

With only 38% schema description coverage, the description should compensate for undocumented parameters, but it only groups a few into vague categories: 'subtasks, tags, dates, and a repeat rule.' It does not add meaning for project_id, parent_task_id, note, flagged, sequential, planned_date, or estimated_minutes, and it does not clarify formats or constraints beyond what the schema already shows.

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 leads with a specific verb and resource: 'Create one task.' It also names the key optional capabilities (subtasks, tags, dates, and repeat rule), and the singular 'one task' helps distinguish it from sibling tools like add_items. An agent can tell what action this tool performs at a glance.

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 conditions are given for when to use add_task instead of add_items, edit_item, or create_project_from_outline, and no alternatives or exclusions are mentioned. The sibling list is present in the context, but the description itself provides no routing guidance.

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

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

Annotations already indicate this is a mutating, non-destructive operation)Skip, and the description adds the useful behavioral detail that existing notes are kept. This does not contradict the annotations Tags, but no additional side effects, failure behavior, or permission requirements are disclosed.

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

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

The description is a single, focused sentence with no filler. It front-loads the key behavior (append without overwriting) and earns every word.

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 low schema coverage and sparse annotations, an agent lacks guidance on how to identify the target note (id vs name), whether either identifier is sufficient, and what happens when both or neither are provided. The description is too brief to support correct invocation in ambiguous cases.

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

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

Schema description coverage is only 25%, and the tool description does not compensate. It adds no meaning for the id/name selector ambiguity, does not explain how item_type relates to the operation, and largely repeats what the schema already states.

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 ('Append') and names the resource ('a task or project note'), also clarifying that it does not overwrite. It does not explicitly name a sibling tool for differentiation, but the behavior is clearly distinguished from overwrite-style 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?

'Without overwriting it' implies the tool is appropriate when existing note content must be preserved. However, there is no explicit guidance on when to use this tool versus alternatives like edit_item, nor any mention of prerequisites or selection strategy.

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

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

Annotations already mark this as non-readonly and non-destructive, and the description aligns by describing a status mutation. It adds the non-obvious behavior that completing repeating items reports the generated instance, which is useful context beyond the schema.

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

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

Two short sentences front-load the core purpose and add one behavioral caveat. There is no filler or redundant restatement of the tool name.

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 core status-changing behavior is clear and the output schema exists, but the description leaves the completion_date parameter unexplained and does not clarify what 'dropped' entails. Together with the missing exclusions in usage guidance, the definition is 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?

With 50% schema description coverage, the schema handles ids and all_occurrences, while the description reinforces the action enum values (complete/incomplete/dropped). However, completion_date receives no explanation in either the schema or the description, so parameter semantics are only adequately covered.

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

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

The description opens with a clear action ('Mark') and target ('tasks or projects'), and enumerates the three distinct states: complete, incomplete, or dropped. This distinguishes it from sibling operations like move_items, edit_item, and remove_items without needing to inspect the 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 first sentence gives clear context for when this tool applies: whenever an item's completion status needs to be set. It does not name exclusions or alternatives, so it falls short of a 5, but the usage context is unambiguous.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds a small amount of behavioral context by revealing the output shape (status breakdown, known estimated minutes), but it does not disclose filtering behavior, aggregation limits, or any other runtime details beyond what annotations provide.

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

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

Two sentences, no filler, and the primary function is front-loaded. The second sentence earns its place by adding concrete use cases. Nothing could be removed without losing value.

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

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

For a tool with 20 optional parameters and very low schema coverage, the description is too thin to be fully self-sufficient. It gives the output shape and a use-case hint, and the output schema likely documents return values, but it leaves the 19 undocumented parameters almost entirely to inference.

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

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

Schema description coverage is only 5%, and the description itself gives no parameter guidance. While parameter names are mostly self-descriptive (days, search, tag_id, etc.), the description does not explain how they combine into 'matching tasks', estimate units, status values, or date-window semantics, leaving a large burden on the agent.

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 a specific action ('Count'), a resource ('tasks'), and the output ('status breakdown and known estimated minutes'). It clearly differentiates from sibling query_tasks by focusing on counts/aggregate scale rather than listing records.

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?

'Use this before listing when you need scale, daily capacity, or a review total' provides clear context for when to reach for this tool. It does not explicitly name alternatives like query_tasks or state when not to use it, but the 'before listing' direction is an effective usage signal.

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

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

Annotations already mark this as non-read-only and non-idempotent, so the description's 'Create' aligns with them. It adds meaningful behavioral context by stating that failures are rolled back via Undo, which is useful for an agent assessing side 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?

Two short sentences, with the core action and prerequisite front-loaded and the failure behavior in the second sentence. No filler or repetition of schema content.

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

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

The description is complete enough for a creation tool: it states what is created, from what input, and what happens on failure. The output schema is present, so return-value documentation is not required.

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

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

Schema description coverage is 100%, and the schema already explains the project object, nested tasks, limits, and optional fields. The description provides no additional parameter-level detail, which is acceptable given the schema's completeness.

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 and resource: 'Create one verified project tree from a user-confirmed outline.' It clearly distinguishes the tool from sibling creators like add_project or add_items by emphasizing a full project tree sourced from a confirmed outline.

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 phrase 'from a user-confirmed outline' gives clear context for when this tool is appropriate. It does not explicitly exclude alternatives like add_project, but it strongly implies the distinguishing prerequisite without being vague.

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

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

Annotations indicate the tool is not read-only, not idempotent, and not destructive, but the description carries the burden of explaining the operation's actual behavior. It does not disclose that originals remain intact, that each call creates new copies, or how project duplication handles subtasks.

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 short sentences with no filler. The template-use note earns its place by giving the primary practical motivation for duplicating a project.

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 core operation and a use case are clear, and an output schema exists. Still, for a tool with multiple modes (task vs project), optional renaming, and subtask behavior, the description leaves important semantics like what happens to the original and how project subtasks are handled implicit.

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 descriptions already cover 'ids' and 'include_subtasks', but the description adds nothing about 'new_name' beyond its bare name. Since schema coverage is 67%, not high enough to excuse the lack of parameter-level help, and 'new_name' remains ambiguous.

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 identifies the action as duplicating tasks or projects, which is a specific verb+resource combo and distinguishes it from creation or editing siblings. It doesn't name sibling alternatives, but the scope is plain enough.

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 phrase 'Duplicating a project is useful as a template' gives an implied use case, which is helpful. However, there is no explicit guidance about when to prefer duplicate_items over add_items or other creation tools, nor any exclusion criteria.

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

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

The annotations already indicate this is a mutating, non-idempotent operation, and the description's 'Edit' aligns rather than contradicts that. It adds that move, tags, dates, and status can be changed, but it does not disclose side effects, persistence, or caveats about replacing versus merging values.

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

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

The single-sentence description is tight and front-loads the core action and resource. It wastes no words, though brevity comes at the cost of important operational detail.

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

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

For a tool with 25 parameters and only 16% schema coverage, a one-line overview is not enough to invoke correctly. Key details about how the target is identified, how optional move/tag/date changes are expressed, and the behavior of clear/replace flags are missing.

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

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

Schema description coverage is only 16%, so the description would need to compensate for 25 parameters, but it only loosely groups fields as 'move, tags, dates, and status.' It does not explain identity selection, clearing fields, moving destinations, tag handling, or date formats.

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 identifies the action ('Edit'), the resource ('a task or project'), and the main areas: move, tags, dates, and status. It does not explicitly differentiate from sibling tools like move_items or complete_items, so it is clear but not strongly distinguished.

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?

There is no guidance on when to use edit_item versus siblings such as move_items, set_repetition, append_note, or complete_items. The description implies broad editing but never states exclusions or narrower alternatives.

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

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

Annotations already flag the tool as mutating and destructive. The description adds meaningful context beyond those annotations by disclosing that deleting a folder also deletes its projects and requires confirmToken. No contradiction exists, though other potential side effects are not discussed.

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 with no filler. The action list is front-loaded, and the critical destructive warning is placed in the second sentence. 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?

With 9 parameters, zero schema descriptions, and several overlapping identifiers (folder_name vs name vs new_name), the description is too sparse to support correct invocation. It does not specify which action uses which parameters, how move identifies the target and parent, or what status does. The output schema does not resolve input-side ambiguity.

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

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

Schema description coverage is 0%, so the description must compensate, but it only explains confirmToken's role. The remaining eight parameters—folder_id, folder_name, new_name, parent_folder_id, parent_folder_name, status, and more—are left unexplained, leaving the agent unable to map actions to required inputs.

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 specific verbs (create, rename, move, delete) tied to the folder resource, making the core function clear. It is clearly mutating compared to query siblings, but it does not explicitly differentiate from move_items or other manage_* tools, so it misses the full distinctiveness bar.

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

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

No explicit when-to-use or alternatives are provided. The only usage hint is that delete requires confirmToken and cascades to projects, which is a precondition warning rather than a selection guide. Usage context is implied by the title and action enum, but not fully articulated.

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 says the tool can 'remove task reminders', but annotations declare destructiveHint=false. Removing a reminder is a destructive operation, so the description contradicts the annotation. The description also fails to disclose side effects or whether removal is reversible.

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 one tight sentence with the core action words front-loaded and a compact parenthetical clarifying reminder modes. No words are wasted.

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?

Even with an output schema, the description is too sparse for a multi-action tool with six parameters and no required fields. It does not specify parameter combinations per action, the difference between task_id and task_name, or how list/add/remove are invoked, and the destructiveHint contradiction further undermines safe use.

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

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

Schema description coverage is only 33% (absolute_date and minutes_before_due), and the description only echoes the absolute/due-relative distinction. It does not explain how task_id, task_name, and notification_id relate to each action, nor which parameters are required for add versus remove. This leaves substantial ambiguity for a six-parameter 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 states a clear verb set ('List, add, or remove') and a specific resource ('task reminders'), with the useful distinction of 'absolute or due-relative'. An agent can identify the tool's job and tell it apart from sibling tools like manage_tag or manage_perspective.

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 say when to use this tool over siblings such as query_tasks, add_task, or manage_perspective, and it gives no exclusions or prerequisites. The usage context is only implied by the tool's name and purpose.

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

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

Beyond the annotations (readOnlyHint=false), the description adds that changes are made in place and that OmniFocus does not permit perspective creation or deletion through automation. This is useful context for an agent forming expectations, though it omits details like defaulting behavior when rules/aggregation are null.

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 with no redundancy; the core action is front-loaded and the platform limitation is stated as a single useful qualifier. Every clause 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?

For a mutating tool with four optional parameters and only 25% schema coverage, the description leaves key operational questions unanswered: how to identify the perspective, what null values mean, and whether rules and aggregation can be updated independently. The existence of an output schema lowers the burden for return-value details, but targeting remains underspecified.

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

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

Schema description coverage is only 25%, and the description does not compensate. It maps conceptually to 'rules' via 'filter rules' but gives no guidance on the two perspective identifiers, the role of aggregation, or which parameters are needed to target and modify a perspective.

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?

States a specific verb ('Update'), a precise resource ('a custom perspective's filter rules'), and the in-place scope. The second sentence clarifies that perspective creation/deletion is unavailable, distinguishing this tool from potential management siblings and making its role 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 clearly identifies the tool as the update path for existing custom perspectives and warns that create/delete operations are not supported via automation. It does not explicitly name alternatives like query_perspectives or list the conditions for selecting perspective_id versus perspective_name, but the boundary is clear enough.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation and destructive nature are covered. The description adds useful domain behavior beyond annotations: 'On-hold tags block next actions.' It does not contradict the annotations.

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

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

The description is two sentences with no fluff and the main operation is front-loaded. The second sentence adds domain context but is not integrated with the parameter schema; still, every sentence earns its place and nothing is redundant.

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 nine parameters, zero schema descriptions, and no output-schema details, this description is far from complete. An agent cannot determine which parameters are required for add vs edit vs remove, which identifier to use (tag_id vs tag_name), or how nesting and on-hold status are set. The output schema exists, so return values need no explanation, but the call semantics remain under-specified.

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 carries the full burden for explaining parameters, but it only loosely maps verbs to the action enum and never clarifies the roles of tag_id, tag_name, new_name, parent_tag_id, parent_tag_name, allows_next_action, or status. 'On-hold tags block next actions' hints at status/allows_next_action but does not specify how to set them.

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

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

The description opens with specific verbs ('Create, rename, nest, or delete') tied to a clear resource ('a tag'), making the tool's purpose immediately evident. It differentiates from sibling tools like query_tags, manage_folder, and manage_perspective by naming the exact tag operations it performs.

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

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

Usage is implied by the mutation verbs and tag resource, but the description gives no explicit guidance about when to choose this tool over query_tags for reading tags or manage_folder for hierarchical management. No alternatives or exclusions are mentioned, so the agent must infer context from sibling 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?

The description adds useful behavior beyond the annotations by noting that a single timestamp is applied and that next review dates are returned. It does not disclose edge-case behavior, such as what happens if some ids are invalid or already reviewed, but the output schema and non-destructive annotation provide some 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 a single, efficient sentence that front-loads the main action and then states the return value. There is no redundancy or filler, and every clause contributes useful information.

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

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

Given the tool's low parameter count, its output schema, and the annotations, the description covers the essential behavior well: what is marked, what timestamp behavior applies, and what is returned. It is slightly incomplete on usage boundaries and parameter details, but those are minor for this simple 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?

The ids parameter is well described in the schema, and the description's 'one timestamp' hints at how review_date behaves. However, the optional review_date parameter lacks explicit semantics such as its format or what null means, so the description only partially compensates for the 50% schema description 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 uses a specific verb and resource: it marks projects as reviewed and states that it returns OmniFocus-generated next review dates. It is clear and unambiguous, but it does not explicitly differentiate itself from sibling tools such as edit_item or complete_items by naming alternatives.

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

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

The phrase 'confirmed projects' implies that the tool should be used after a user has explicitly confirmed that projects were reviewed, which gives some usage context. However, the description does not state when to prefer this over related actions, nor does it mention any exclusions or prerequisites.

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

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

Annotations already indicate a mutating operation (readOnlyHint=false) and non-destructive behavior (destructiveHint=false). The description adds one meaningful behavioral detail: 'Cycles are rejected before any move,' which is a safety guarantee beyond the annotations. However, it does not disclose other potential side effects, partial failure handling, or permission requirements, so the added value is moderate.

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

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

The description is two sentences with no redundant information. The primary purpose is front-loaded in the first sentence, and the second sentence focuses on a critical edge case. Every word earns its place.

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

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

Given that this is a single-parameter tool with a full input schema, annotations, and an output schema present, the description adequately covers the core action and the most important constraint (cycle rejection). It could be more complete by explaining behavior on partial failure or whether multiple moves are atomic, but the essential information for calling the tool correctly is present.

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

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

Schema description coverage is 100% and already documents the moves array structure, requiring taskId and exactly one destination (projectId, parentTaskId, or moveToInbox=true). The description's mention of 'project, parent task, or the Inbox' essentially restates these destination options, adding little semantic value beyond the schema. The cycle-rejection note is behavioral, not parameter-specific.

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 ('Move') with a clear resource ('tasks') and lists destination types ('project, parent task, or the Inbox'). This clearly distinguishes the tool from siblings like add_task, edit_item, or remove_items, which handle create/edit/delete operations. The additional note about cycle rejection further specifies 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?

The description states what the tool does but provides no explicit guidance on when to use it versus alternatives like edit_item or duplicate_items. There is no mention of exclusions, prerequisites, or conditions that would help an agent choose this tool over others. The usage context is only implied by the verb 'move'.

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

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

Annotations are all false, so they provide no safety profile. The description states what actions exist but does not disclose side effects, such as whether clean-up modifies or deletes data, whether undo/redo is irreversible, or what happens to the current OmniFocus state. This is too thin for a mutating session utility.

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?

A single sentence with three clear action groups and no filler. It is efficient and front-loaded, though slightly too terse to fully carry the tool's complexity.

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 four parameters, an action enum, and no parameter documentation, the description is not sufficient for an agent to know which parameters are required for each action. The output schema helps with return values, but the input semantics are largely unspecified.

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

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

Schema description coverage is 0%, and the description does not explain how id, name, or item_type map to the four actions. For a multi-mode tool where parameters are likely action-dependent, the description leaves the invocation contract completely undocumented.

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 names three concrete actions (undo/redo, clean-up, reveal) with a specific resource (OmniFocus), so an agent can distinguish this session-level utility from query/add/edit siblings without opening the 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 actions listed imply when the tool is useful, but the description gives no explicit guidance about when to choose this over sibling tools, nor does it state conditions or exclusions. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: it defines the tool as a health check, lists the specific status categories returned, and warns that it never dumps tasks. No contradiction with annotations.

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

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

Two short sentences accomplish a great deal: the first states what the tool reports, the second gives usage timing and an explicit scope boundary. Every word earns its place; no filler or redundant restatement.

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

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

Given the tool's low complexity—one optional parameter, rich annotations, and an output schema—the description is complete enough for an agent to know when to call it and what it provides. The launch parameter is documented in the schema, and the output schema removes the need to describe return values in prose.

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

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

Schema description coverage is 100%: the single optional launch parameter is fully documented in the schema ('If true, try to bring OmniFocus forward'). The tool description itself does not discuss the parameter, but at this coverage level the schema carries the semantic burden, so a baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a health check for OmniFocus and enumerates the status data it provides: running state, Pro vs Standard, undo availability, and headline counts. It distinguishes itself from task-oriented siblings by explicitly stating 'It never dumps tasks,' though it does not name a specific sibling for comparison.

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

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

The description gives explicit usage triggers: 'Use this first when a session starts or a call fails.' It also provides a meaningful exclusion by clarifying that it never dumps tasks, implying that task retrieval should go elsewhere. However, it does not name an alternative tool for those cases, stopping short of fully explicit routing.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds one behavioral detail: that 'detailed' includes child projects and subfolders, which is useful context. Still, it does not disclose pagination behavior, performance implications, or any other runtime traits beyond what annotations already provide.

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

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

The description is very short and front-loads the core action, with the useful detail about 'detailed' output placed second. Every sentence earns its place and there is no fluff. The brevity is appropriate, though it sacrifices semantic completeness.

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 six parameters, no schema descriptions, and no usage guidance, the description is too sparse to fully support correct invocation. The output schema exists and annotations cover safety, but the tool's filtering, pagination, and search capabilities are not explained. This is a meaningful gap for an agent deciding how to query folders correctly.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It only addresses the 'output' parameter by mentioning 'detailed' mode. Parameters like cursor, search, folder_id, and folder_name are left wholly unexplained, forcing the agent to rely on names alone. This is insufficient for a six-parameter 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 verb 'List' and the resource 'OmniFocus folders', making the tool's primary purpose obvious. It also adds that 'detailed' output includes child projects and subfolders, which clarifies the scope. However, it does not explicitly distinguish this from sibling tools like query_projects or manage_folder, so it falls just short of full differentiation.

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?

There is no guidance on when to use this tool versus alternatives such as query_projects or query_tasks. The description implies it is for listing folders, but it does not mention filtering, pagination, or when the detailed output mode is preferred. This leaves the agent to infer usage context from the parameter names alone.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavior beyond annotations: custom perspectives require Pro, and the tool returns perspective metadata/filter rules rather than tasks. This is consistent with the readOnlyHint.

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 short, front-loaded with the main purpose, and every sentence contributes: what it lists/reads, the Pro requirement, and the explicit exclusion with an alternative. No filler.

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

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

With annotations and an output schema present, the description covers the essential invocation context: scope of the query, Pro requirement, and the task-returning exclusion. The only notable gap is not specifying how to target a custom perspective for the 'get' action, which is modest for this simple read-only tool.

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

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

The schema already documents 'action' and 'perspective_name', and description coverage is partial (67%). The description adds conceptual context about built-in vs custom perspectives and filter rules, but it does not clarify how perspective_id vs perspective_name should be used for the 'get' action, especially since no parameters are required.

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

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

The description uses specific verbs ('List', 'read') and a clear resource ('perspectives'), then explicitly distinguishes itself from query_tasks by stating it does not return the tasks inside a perspective. This makes the tool's scope easy to identify.

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

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

It gives an explicit alternative for the excluded use case: 'use query_tasks with source=custom for that.' It also calls out the OmniFocus Pro requirement for custom perspectives, which is a practical prerequisite an agent needs to know before invoking.

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

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

Annotations already cover safety (read-only, idempotent, non-destructive). The description adds that results include review metadata and stalled detection, but it does not explain pagination behavior or the meaning of 'stalled' beyond what the view parameter schema already states.

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?

A single front-loaded sentence with no wasted words. It states the core action and the two distinguishing features efficiently.

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 read-only annotations and an output schema, default calls are safe and understandable. However, given 11 parameters, low schema coverage, and no guidance on filter combinations or view/output behavior, the description is only minimally complete for more nuanced use.

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

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

Schema description coverage is only 18%, so the description needed to compensate for the 11 parameters. It does not explain limit, cursor, output, search, status, sort_by, or folder/project filters. The phrase 'stalled detection' maps to the view enum, but most parameter semantics are left to inference.

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?

Uses a specific verb ('List') and resource ('projects'), and adds distinctive scope: review metadata and stalled detection. This clearly separates it from sibling tools like query_tasks and query_folders.

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 resource 'projects' makes the basic use case clear, but there is no explicit guidance about when to choose this over query_tasks, count_tasks, or query_folders. Usage is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description adds value with the hierarchy path detail. No mention of pagination or output format, but with annotations covering safety, the description adequately complements beyond 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?

One sentence, front-loaded with the primary action and key feature (hierarchy paths). Zero redundancy; every word earns its place.

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

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

For a read-only query tool with an output schema and clear annotations, the description covers the essential behavior. It doesn't explain pagination or detailed output, but these are standard and likely inferable from schema defaults. Adequate for the tool's complexity.

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

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

Schema coverage is only 14% (only 'search' has a description). The description mentions 'search' but doesn't explain limit, cursor, output, status, tag_id, or tag_name. The phrase 'List or search' conveys the general purpose but fails to illuminate the role of most parameters, leaving the agent to guess.

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

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

The description clearly states the verb ('List or search') and resource ('tags') with explicit detail about hierarchy paths. It differentiates from siblings like manage_tag (which implies modification) and query_tasks (different 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?

It clearly states when to use the tool (listing/searching tags). The sibling manage_tag implicitly covers modification, but the description doesn't explicitly mention when to use that alternative. The hierarchy path example gives context for searching, but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context by stating 'Results are paginated and compact by default,' which agents must know to retrieve complete data, and it clarifies custom-perspective semantics.

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

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

Three short sentences carry the core purpose, pagination behavior, the primary alternative, and the main pitfall. Every sentence earns its place, and the most important information 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?

For a 43-parameter read tool, the description cannot enumerate every filter, but the schema descriptions cover the parameters in detail and an output schema exists. The description supplies the high-level invocation behavior, pagination, the recommended alternative, and the key source=custom clarification, making it complete enough for safe use.

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

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

Schema description coverage is 98%, so the baseline is 3. The description adds value beyond the schema by explaining that custom perspectives are saved views rather than tags, which is not obvious from the parameter list alone and helps agents choose between source=custom and tag-based filtering.

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

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

The description opens with 'Read tasks from Inbox, Flagged, Forecast, tags, projects, custom perspectives, or an ad-hoc filter,' naming the verb, the resource, and the supported sources. This goes well beyond the title 'Query tasks' and clearly separates it from sibling tools like count_tasks and query_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?

It explicitly directs agents to 'Use count_tasks when you only need totals,' naming the alternative and the condition that selects it. The note that 'Custom perspectives (source=custom) are saved views, not tags' also prevents a likely misuse of the tag parameters.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds useful behavioral context that images may be returned as image content, which helps the agent anticipate response format. It does not contradict the annotations.

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

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

Two concise sentences with no wasted words. The operation is stated first, and the important image-content behavior is front-loaded in the second sentence.

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

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

For a simple read operation with two required parameters and strong annotations, the description covers the essential behavioral nuance. It does not specify non-image return formats, but the lack of an output schema and the tool's straightforward nature keep this gap minor.

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

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

Schema description coverage is 100%, so both task_id and attachment_id are already documented in the schema. The description adds minimal extra meaning beyond noting the attachment was previously listed, which is consistent with baseline expectations.

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

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

The description clearly states the tool reads one attachment from a task, with a specific verb and resource. The phrase 'previously listed on a task' narrows the scope and distinguishes it from broader query or listing 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 provides clear context: use for one attachment that has already been listed on a task, implying prior retrieval of the task's attachments. It does not explicitly name an alternative or exclusion, but the tool is the only attachment-reading sibling, so guidance is adequate.

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?

It reveals an important two-phase behavior: the first call only returns a cascade preview and token, and only the second call performs the deletion. This goes beyond the destructiveHint annotation by explaining how the destructive action is gated and previewed.

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 cover purpose, target types, and the required two-call workflow with no filler or redundant restatement of the schema. The core 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?

Given the destructive annotation and presence of an output schema, the description supplies all essential invocation information: what is deleted, how the preview/token handshake works, and that the second call is the executing one. No critical step is left to inference.

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

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

The input schema already describes ids and confirm_token thoroughly, but the description adds the workflow that binds them: ids initiate the preview, and the returned token is required to execute deletion. This provides meaning beyond the schema's standalone field 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 opens with a concrete verb and resource: 'Delete tasks, projects, or folders.' This makes the tool's intent unambiguous and distinguishes it from sibling tools like complete_items, move_items, or duplicate_items, which operate on the same item types but do not delete them.

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 clearly establishes the use case: removing tasks, projects, or folders. It does not explicitly name exclusions or alternative tools, but the delete vs. move/complete/duplicate distinction in the sibling list makes the intended context obvious.

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

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

Beyond the annotations (which only mark the operation as non-read-only/non-idempotent/non-destructive), the description adds a meaningful guarantee: it restores the previous repetition rule on failure. It also communicates an OmniFocus version prerequisite. This is useful behavioral context, though it stops short of describing auth or side 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?

Two short sentences, front-loaded with the action and resource, and the failure guarantee earns its place. There is no filler or restatement of the tool name.

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

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

For a tool with six optional parameters, low schema coverage, and minimal annotations, the description omits the operational details needed to call it correctly. It covers high-level behavior and rollback, but not how to combine or choose parameters; the output schema covers return values, but parameter semantics remain under-specified.

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

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

With only 33% schema description coverage, the description needed to clarify how the six parameters relate, but it does not. It never explains task_id vs task_name, clear vs method/rule_string, or catch_up_automatically; those are left to inference from 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 names a concrete action set (set, update, clear), the exact resource (a task's OmniFocus repetition rule), and a version constraint (4.7+). This makes it easy to distinguish from generic sibling tools like edit_item or add_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?

The intended use is implied by the resource and verb set, but no explicit when-to-use or when-not-to-use guidance is provided. It does not mention alternatives such as edit_item, nor what conditions should lead an agent to choose this tool over them.

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