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

Annotations already carry the safety profile (readOnlyHint=false confirming a write, destructiveHint=false). The description adds the mode distinction but little else about behavior — no side effects, no mention of what happens when a relative notification is set on a task without a due date, and no duplicate/replay semantics beyond what the idempotencyKey schema text already provides.

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 the verb and resource front-loaded and the mode distinction appended via em-dash. Every word earns its place; zero filler or 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 schema (100% coverage, detailed semantics) and output schema carry substantial load, so the short description suffices for the core operation and timing modes. Minor gaps: it does not note that a task must be identified via taskId or taskName, and does not point to sibling lifecycle tools (list_notifications, remove_notification).

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

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

Schema coverage is 100% with rich parameter descriptions (date interpretation rules, enum semantics, idempotency replay behavior, due-date requirement for minutesBefore). Per the rubric, baseline 3 applies; the description only restates the absolute/relative distinction already encoded in the type enum, adding no parameter-level 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?

States a specific verb ('Add') and resource ('notification (reminder) to a task'), plus the two timing modes (absolute date or relative to due date). The verb 'add' clearly differentiates it from sibling tools list_notifications and remove_notification, so an agent can distinguish them without opening schemas.

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 — use this when attaching a reminder to a task, choosing between absolute and relative timing. However, the description gives no explicit when-to-use/when-not-to-use guidance and does not route to alternatives such as list_notifications or remove_notification for managing existing notifications.

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 establish this as a non-read-only, non-destructive write), the description discloses a genuine behavioral trait: the tool performs no duplicate detection, so creating a task with an existing similar name can produce a duplicate unless the agent runs the pre-check. This meaningfully exceeds annotation coverage.

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

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

Two sentences with zero filler. The primary action is front-loaded, and the conditional dedup instruction earns its place as the single most important operational caveat. Every word carries signal.

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 13-parameter, 1-required write tool, the combination of a fully self-documenting schema, annotations, an output schema, and the dedup guidance leaves nothing needed to invoke the tool correctly unexplained. The only marginal gap is explicit routing to batch_add_items for bulk creation.

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% — all 13 parameters (name, note, tags, tagIds, dates, idempotencyKey, parentTaskId, etc.) are individually documented. Per the baseline, the description need not add parameter detail. Its dedup note relates to the name parameter but supplies workflow guidance rather than new 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 states a specific action with a clear verb and resource: 'Add a new task to OmniFocus.' This distinguishes it from sibling tools like add_project, edit_item, or batch_add_items, and the duplicate-check instruction signals this is the single-task creation entry point.

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

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

The description gives an explicit precondition: before creating a possibly-duplicate task, call find_similar_tasks with the same name and reuse the returned id on a strong match. This is clear when-to-use guidance, but it does not name exclusions or alternatives such as batch_add_items for bulk creation.

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 state readOnly=false and destructive=false, and the description merely says 'Add', which is consistent but adds no behavioral context beyond those annotations. It does not disclose idempotency behavior, failure semantics for invalid tag IDs or ambiguous folder names, or what happens after creation.

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 redundant wording and is easy to parse. It is concise but provides no additional structure or high-level context beyond the bare 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?

Given the tool has 12 parameters and non-trivial behavior around folder resolution, tag IDs, and idempotency, the one-sentence description alone is not complete. However, the rich parameter schema and presence of an output schema compensate for most invocation details, leaving only high-level usage and behavioral guidance 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 schema has 100% description coverage, so all 12 parameters are already documented in detail. The tool description adds no parameter-level meaning, but because the schema fully covers parameter semantics, the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Add') and resource ('project') and names the target system ('OmniFocus'), clearly identifying what the tool does. This also distinguishes it from sibling tools like add_omnifocus_task, create_folder, or create_tag, which involve different resources.

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 usage guidance is provided. There is no discussion of when to use this tool versus alternatives such as add_omnifocus_task for tasks or convert_task_to_project, and no prerequisites or exclusions are mentioned. The agent must infer usage solely from the tool name and description.

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 meaningful behavior beyond the readOnlyHint=true annotation: output is markdown-formatted counts/rates/lists/dates, and the tool intentionally provides no scores or recommendations. This helps an agent set expectations about the return value and its limitations. It does not mention the cache behavior, but the fresh parameter already documents that in 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 tight sentences with no filler. The action, scope, output format, and key caveat are all front-loaded, and every clause earns its place. This is an exemplar of concise tool documentation.

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 rich schema covering all 7 parameters and the presence of an output schema, the description is complete for call selection and invocation. It states what the tool does, what it returns, and an important behavioral boundary. Nothing critical for an agent to invoke this tool correctly is 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 100%, so the schema already documents all parameters thoroughly. The description only repeats the analysis enum names without adding parameter-level detail. Per the calibration baseline, 3 is appropriate because the description adds no semantic value beyond the schema for parameters.

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

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

The description opens with a specific verb and resource: 'Read-only analytics over the OmniFocus database', then enumerates the four supported analyses. This clearly distinguishes the tool from sibling CRUD/search tools and even from other read-only tools like dump_database or get_project_counts by framing it as analytics rather than raw retrieval.

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 conveys when to use the tool: whenever an agent needs summarized analytics such as health_snapshot, velocity, overdue_clusters, or stalled_projects. The phrase 'no scores and no recommendations — so the caller does the interpreting' also tells the agent that this tool is not for decisions requiring judgment. However, it does not explicitly name alternatives or exclusion conditions relative to sibling 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?

The description goes beyond the destructiveHint annotation by specifying that confirm:true is required for undo/redo and that without it these operations only report state. It also notes sync is fire-and-forget. This adds valuable behavioral context beyond the annotations.

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

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

Two tight sentences that front-load the purpose and immediately highlight the destructive operations. No wasted words; 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?

Despite 10 parameters and 7 operations, the description covers the operations, the confirm requirement, and the plural/singular distinction. Output schema exists, so return values are handled. An agent has everything needed to call this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics: it explains the operation enum values, clarifies the confirm flag's effect, and distinguishes projectId vs projectIds (singular/plural) for reveal vs set_focus. This is more than the schema provides.

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

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

The description states a clear purpose: 'Application-level OmniFocus control' and enumerates the exact operations (sync, undo/redo, focus, reveal). It is specific and distinct from the many task-level sibling tools, so an agent can easily tell this tool is for app-wide control.

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 context by labeling the tool as 'Application-level' and explaining the destructive nature of undo/redo with the confirm requirement. It doesn't explicitly say 'use this instead of X', but the scope is clearly defined and differentiates from the task-centric siblings.

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

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

Annotations already indicate not read-only and not destructive; the description adds the key behavioral detail that existing content is preserved. However, it doesn't disclose behavior for missing notes, permission requirements, or side effects. With annotations covering the safety profile, this is adequate but not rich.

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 no filler; the verb and direct object are front-loaded. Could arguably be 5, but it lacks any structured guidance for the deprecated aliases or optional parameters, so 4.

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 schema leaves id and itemType optional, yet the description doesn't explain what happens when they are omitted or how the target is resolved. For a mutation tool with multiple parameters and deprecated aliases, the description alone is insufficient for correct invocation.

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

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

Schema coverage is 100%, so parameters are documented. The description adds no extra meaning about the optionality of id/itemType or the deprecated aliases. At high schema coverage the baseline is 3; no additional value is provided.

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

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

States the specific operation (append) and resource (task or project note), and explicitly notes the non-destructive behavior ('without overwriting'), which distinguishes it from edit-type tools. It doesn't name sibling tools explicitly, so not a 5.

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

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

No guidance on when to use this vs alternatives like edit_item or batch_edit_items, no prerequisites (e.g., must supply id/itemType), and no exclusions. The one-sentence description implies 'use to append' but offers no decision support.

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 (readOnlyHint=false, destructiveHint=false) establish the write-not-destructive profile; the description adds behavioral context beyond that: dryRun preview, stopOnError, and atomic rollback. The rollback disclosure is genuinely meaningful — the agent learns failed batches delete already-created objects. Nothing contradicts 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?

Three sentences with zero filler: purpose first, then a compact feature summary, then an actionable pre-condition warning. Every sentence earns its place and nothing restates the title or schema verbatim.

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 complex tool (nested item array, atomicity, rollback, dryRun, idempotency), but the schema exhaustively documents all parameters, an output schema exists, and annotations cover the safety profile. The description covers purpose, key behaviors, and the critical duplicate-prevention workflow. Only minor gap: no explicit contrast with single-item add siblings, though the batch scope is stated.

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

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

Schema coverage is 100%, and the schema's per-property descriptions already explain tempId/parentTempId wiring, date parsing semantics, atomic/stopOnError interaction, and idempotencyKey. The description names the key semantics (hierarchy wiring, dryRun, atomic rollback) but adds no depth that the schema lacks, so the baseline 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?

States a specific verb ('Add'), resource ('tasks or projects to OmniFocus'), and scope ('multiple... in a single operation'). The batch nature distinguishes it from single-add siblings (add_omnifocus_task, add_project), and the mention of 'add' separates it from batch_edit_items. The cross-reference to find_similar_tasks further orients the agent.

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 final sentence gives explicit pre-use guidance: 'Before adding tasks that may already exist, call find_similar_tasks for each name and drop or replace any item with a strong match' — naming the alternative tool and the condition that triggers it. It also explains the rationale ('batch creation multiplies duplicates'). It does not explicitly exclude single-item add tools, but the 'multiple... in a single operation' phrasing makes the batch context clear.

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

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

Annotations already mark this as destructive (destructiveHint=true), so the write nature is known. The description goes further by disclosing non-atomic behavior ('Earlier edits remain if a later item fails') and per-item verification, which are not visible in annotations or 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 sentences, front-loaded with the core capability and immediately followed by the critical failure-behavior caveat. Every clause carries information; nothing is redundant or generic.

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 extensive schema (which documents all parameters and their semantics), an output schema for return values, and annotations covering safety, the description supplies exactly the missing behavioral context: batch scope, non-atomicity, and verification. An agent selecting and invoking the tool has all necessary cues.

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%, with detailed per-property explanations (date formats, ID vs name resolution, tag creation, status enum meanings). The tool description adds no parameter-specific detail, so it correctly relies on the schema's rich documentation.

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

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

The description states a specific verb ('Edit'), resource ('tasks/projects'), a concrete bound ('up to 100'), and distinctive capabilities ('preview and per-item read-back verification'). It clearly differentiates this from sibling tools like edit_item and batch_add_items.

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 a batch use case with 'in one call' but does not explicitly contrast with single-item edit_item or state when to choose this tool over alternatives. The context is inferred rather than spelled out.

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

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

Annotations already indicate destructiveHint=true, and the description's 'Move' matches that destructive intent without contradicting it. The description adds the scope of the operation but does not disclose details like partial failure behavior, conflicts between destinations, or atomicity. With annotations carrying the destructive-safety signal, this is acceptable but not rich.

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 with no filler. It front-loads the action, scope, and allowed destinations, making the tool's core purpose immediately clear.

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

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

The schema and output schema cover a lot, but the description does not clarify an important cross-parameter constraint: whether exactly one destination must be specified and what happens if multiple target parameters are provided. Since only 'tasks' is required in the schema, an agent might invoke the tool without a destination and fail. This gap keeps the definition from being 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 description coverage is 100%, so the parameter names and descriptions already explain each field. The description adds general destination types (project, parent task, inbox) that map onto the target parameters, but it does not add meaning beyond what the schema already provides.

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

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

States a specific verb and resource: 'Move multiple tasks to a project, parent task, or inbox in a single operation.' It clearly scopes the tool to batch operation over multiple tasks, distinguishing it from the sibling move_task which handles a single 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 description clearly conveys when to use this tool: when moving multiple tasks at once. It doesn't explicitly name alternatives or exclusions, but the 'multiple tasks' and 'single operation' phrasing provides enough context to route an agent toward this tool for batch moves and away from single-task equivalents.

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 destructiveHint annotation already communicates that this is a destructive operation, and the description's 'Remove' is consistent with that. The description does not add much beyond the annotation except the batch/single-operation scope; it does not mention irreversibility, cascading project deletion, or failure behavior. With annotations present, the bar is lower, so this is adequate but not exceptional.

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 front-loaded sentence with no filler. It names the action, the target resource, and the batching behavior without wasting any 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?

For a destructive batch operation, the description is terse, but the rich input schema, destructive annotation, and presence of an output schema cover most operational detail an agent needs. It would be slightly stronger with explicit guidance about using remove_item for single removals, but the tool is otherwise complete enough to select and invoke 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 100%, and the schema already explains items, itemType, id, name, and dryRun clearly, including the important fallback rule for id vs name. The tool description adds no parameter-level guidance beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Remove'), a clear resource ('multiple tasks or projects from OmniFocus'), and a scoping qualifier ('in a single operation'). This makes it easy to distinguish from single-item siblings like remove_item and from add/edit batch siblings like batch_add_items and batch_edit_items.

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 'multiple... in a single operation' clearly indicates when this tool is appropriate: when several items need deletion at once. It does not explicitly name alternatives or state when not to use it, but the batch context is clear enough to guide selection.

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 only indicate that the operation is non-read-only and non-idempotent. The description adds meaningful behavioral context: already-completed tasks are unchanged, while repeating tasks advance on each call, which explains the non-idempotency and warns against retries. This goes beyond the annotation flags.

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

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

Three short sentences with no filler. The core action is front-loaded, and the important edge cases about already-completed and repeating tasks are stated 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?

For a single-parameter tool with an output schema and clear behavioral warnings, the description is complete enough for correct invocation. No additional prerequisites, return-value explanations, or alternative routing are necessary for this level of 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 description coverage is 100%, and the tool-level description adds no parameter-level detail beyond what is already in the schema. The task_id parameter is documented with the same behavioral notes, so the description does not compensate beyond the schema baseline.

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 verb ('Complete') and resource ('a task'), and clarifies the action's semantics by noting that already-completed tasks are unchanged while repeating tasks advance. It does not explicitly contrast with sibling tools like uncomplete_task, but the verb and resource are enough to identify the tool's role.

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

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

The description provides clear context that completing a task is the intended action and warns against blind retries because repeating tasks advance on each call. It does not name alternatives or exclusions, but the retry warning is practical guidance for when not to call again.

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

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

The description discloses useful non-obvious behavior: subtasks, tags, and notes are preserved, and a missing folder defaults the project to the library top level. But it leaves the fate of the original task ambiguous and does not discuss reversibility or error behavior; with all annotations false, the description carries this burden.

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

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

Two sentences, front-loaded with the core action, then preservation behavior and default placement. Every sentence earns its place with no redundant 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?

The schema covers all parameter semantics and an output schema exists, so the description plus schema give an agent enough to invoke the tool correctly. The main remaining gaps are an explicit alternative-routing rule and the ambiguous fate of the original task, which are minor at this complexity level.

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?

All five parameters already have full schema descriptions, so the description needs little compensation. It adds general context about folder default and preservation, but no new parameter-level detail 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 uses a specific verb ('Promote') and resource ('an existing task into a full project'), and adds distinguishing preservation semantics (subtasks, tags, note). This clearly separates it from siblings like add_project or move_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 trigger condition is clear: use it when an existing task should become a full project. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full exclusion 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 non-read-only, non-destructive write, and the description adds 'new' plus optional nesting. It does not disclose edge behaviors like duplicate-name handling or missing-parent handling, but it does not contradict the annotations either.

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, readable sentence with no filler. It is front-loaded with the core action and includes the key nesting option, though it is slightly redundant with the title.

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 low-complexity creation tool with full schema coverage, annotations, and an output schema, the description is largely sufficient to invoke the tool correctly. The main missing piece is explicit sibling routing, but that is a usage-guidance gap rather than a fundamental completeness failure.

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

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

Schema description coverage is 100%, so the schema fully documents the parameters. The description's 'optionally nested under a parent folder' adds little beyond the parent parameter's own schema description, which already says a parent folder name or ID can be supplied and that top-level is used if omitted.

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 ('Create') and resource ('new folder in OmniFocus'), and adds the useful nesting qualifier. It is unambiguous, though it does not explicitly distinguish itself from sibling tools like add_project or create_tag.

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 given on when to use this tool versus related alternatives such as add_project, create_tag, or update_folder. The optional-parent hint is functional, not selection guidance, so the agent must infer appropriateness from the tool name 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 readOnlyHint=false and destructiveHint=false, so the mutating but non-destructive nature is covered. The description adds a useful behavioral detail about optional parent nesting, but does not disclose behaviors like duplicate-name handling or side effects beyond creation.

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 that immediately states the verb, resource, domain, and the key optional behavior. There is no filler or repetition of schema details.

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 parameter count, full schema coverage, annotations, and an output schema, the description is nearly sufficient. It could add a note about duplicate names or explicit alternatives, but nothing essential is missing for a basic create 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?

Schema description coverage is 100%, so the schema already fully documents name, parent, and idempotencyKey semantics. The description's phrase 'optionally nested under a parent tag' paraphrases the parent parameter but adds little 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 names a specific action ('Create'), a specific resource ('a new tag'), and the domain ('in OmniFocus'), plus the optional nesting behavior. This clearly distinguishes it from siblings like update_tag, delete_tag, and list_tags.

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 makes it obvious when to use this tool: when creating a tag, including an optional parent for nesting. It does not explicitly say 'use update_tag for modifications', but the verb choice and context provide clear guidance without ambiguity.

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 destructiveHint=true, and the description adds meaningful detail beyond that by warning that all projects inside the folder will also be deleted. This is precisely the kind of behavioral context an agent needs before invoking a destructive 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?

The description is short and front-loads the core action, with the warning immediately following. Every sentence earns its place, though the first clause largely restates the title.

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 single-parameter destructive tool with a complete schema and output schema, the description is sufficiently complete. The destructive warning covers the most important operational consequence, and no other missing context would prevent correct invocation.

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

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

Schema description coverage is 100%, so the parameter name_or_id is already fully documented. The description adds no additional parameter-level detail beyond repeating the warning, so the baseline score of 3 is appropriate.

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

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

States a specific verb and resource ('Delete an OmniFocus folder') and immediately adds the critical destructive consequence. This clearly distinguishes it from other folder-related tools like create_folder, update_folder, and get_folder.

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 no guidance on when to use this tool versus alternatives such as remove_item or batch_remove_items. The intended use is implied by the name and first phrase, but there is no explicit context, prerequisites, or 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?

The annotations already communicate that this is destructive (destructiveHint=true) and not read-only, so the description adds no new behavioral context. It does not disclose irreversible effects, what happens to tasks using the tag, or any deletion constraints. There is no contradiction with annotations, but no value beyond them either.

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, zero-waste sentence that front-loads the core action and resource. It is concise, but it is also minimal enough that some behavioral or usage context is absent, which keeps it from a perfect score.

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 destructive tool with an output schema and annotations, the definition is minimally viable: the agent knows what to call and what argument to provide. However, it lacks any mention of side effects or conditions for safe deletion, which matters for a destructive 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?

Schema description coverage is 100%, with one clearly documented required parameter, name_or_id. The description itself adds no parameter-level meaning, but the schema already carries the semantic weight. A baseline of 3 is appropriate here.

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 verb and resource: 'Delete an OmniFocus tag.' This is clear enough to identify the operation, and the resource type 'tag' naturally distinguishes it from siblings like delete_folder and remove_item. It does not explicitly call out sibling differentiation, so it stops short of a full 5.

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 no guidance on when to use this tool versus alternatives such as remove_item, batch_remove_items, or delete_folder. There is no stated context, prerequisite, or exclusion. The agent must infer usage entirely from the name and resource type.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value by noting the database state is 'current' and the parameter descriptions disclose important behavioral details: completed/dropped tasks are capped at 50 per project and the report notes omissions. This goes beyond the annotations.

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

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

The description is a single concise sentence that front-loads the core purpose. The parameter descriptions carry the detailed behavioral information, which is appropriate placement. 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?

The tool has an output schema, so return values are documented elsewhere. The description plus rich parameter descriptions cover the key behaviors (completion cap, recurring duplicate collapsing). It's slightly incomplete in not stating the overall scope of what 'current state' includes (e.g., projects, tasks, folders, tags), but the output schema likely covers that.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description itself doesn't add parameter-level meaning beyond what the schema provides, but the schema's parameter descriptions are rich (explaining defaults, caps, and the recurring-duplicate collapse behavior). 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 'Gets the current state of your OmniFocus database' clearly identifies the tool as a read-only database dump operation. It distinguishes it from sibling tools like get_flagged_tasks or get_inbox_tasks by its broad scope, though it doesn't explicitly name a sibling alternative.

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 this is the tool to use when you need the full current state of the database, as opposed to specific filtered views. However, it doesn't explicitly state when to use this over alternatives like filter_tasks or search_items, 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 the operation is neither read-only nor destructive. The description adds useful detail about which fields are copied (name, note, dates, flags, tags) and the optional destination project. It leaves open whether unlisted data such as subtasks, attachments, or repetition are excluded, and it does not explicitly state that a new task is created.

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 front-loaded, single-sentence description conveys the action, resource, optional project behavior, and copied fields with no filler. Every phrase 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?

With full schema coverage and an output schema present, the description covers the core purpose adequately. It still leaves some call-relevant ambiguity: default project placement when no project is supplied, interaction between taskId and taskName, and whether non-listed data is silently omitted.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters, setting the baseline at 3. The description's copied-fields list lightly reinforces includeNote/includeTags but adds little beyond 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 states a specific action ('Duplicate') on a clear resource ('an existing task') and lists the copied fields, which makes the tool's purpose immediately understandable and distinct from edit/move siblings. It does not explicitly contrast itself with any sibling, so it stops 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?

Usage is implied: an agent can infer that this tool is for duplicating tasks, and the optional different-project behavior adds context. However, there is no explicit when-to-use or when-not-to-use guidance, nor any reference to alternatives like move_task or edit_item.

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 carry readOnlyHint=false and destructiveHint=true, so the description does not need to restate that this mutates data. However, it adds little behavioral context beyond what the parameter schema already shows — no mention of permanence, side effects, ambiguous-ID behavior, or the dryRun preview option. There is no annotation contradiction.

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

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

The description is a single front-loaded sentence that clearly opens with the tool's purpose before listing supported operations. It is dense but not bloated; the list is reasonable for a tool of this breadth.

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 very rich input schema, output schema, and annotations cover most invocation details, so the description need not explain parameters or return values. Still, the missing usage guidance and lack of sibling differentiation leave the description somewhat incomplete as a stand-alone decision aid.

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

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

Schema description coverage is 100%, so the input schema fully documents all 28 parameters. The description's 'Supports:' list mostly mirrors schema property names and categories, adding convenience but no deeper meaning beyond what the schema already provides.

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

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

The description clearly states the tool edits tasks or projects in OmniFocus and enumerates concrete operations (rename, dates, tags, status, etc.). It does not explicitly differentiate itself from siblings like complete_task, move_task, or batch_edit_items, but the verb+resource and capability list make its scope understandable.

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 about when to use this tool instead of sibling tools such as complete_task, uncomplete_task, move_task, batch_edit_items, or append_to_note. The description implies it is the general-purpose editor, but it never states exclusions or routing rules.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the key non-mutating behavior. The description adds little beyond a feature list (e.g., 'offset paging') and does not disclose edge cases or side effects, but 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 a single dense sentence with no filler, front-loaded with 'Advanced task filtering'. It packs many meaningful feature categories into a compact overview, though it reads as a long laundry list and could be structured with examples or bullets for easier scanning.

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 enormous 55-parameter schema with descriptions and a declared output schema, the description provides a sufficient high-level map of capabilities. It doesn't include examples or common usage patterns, but the schema's per-parameter descriptions fill most 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 100%, with every parameter individually described. The tool description adds a high-level conceptual grouping—and/or/not clauses, countOnly, field projection, offset paging—but does not provide any parameter-level detail beyond what the schema already gives.

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 verb and resource: 'Advanced task filtering' of tasks, and enumerates the dimensions (status, dates, project, folder tree, tags, name/regex, note, repeat, estimate). It clearly distinguishes itself from simpler sibling getters via the word 'Advanced', though it never names an alternative tool directly.

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

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

The description implies use for complex or multi-dimensional filtering but gives no explicit when-to-use guidance or exclusions. It doesn't route the agent to simpler siblings like get_inbox_tasks or get_flagged_tasks when advanced clauses aren't needed, leaving the selection largely to inference.

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 readOnlyHint annotation already signals a safe read operation. The description adds valuable behavioral context beyond that: it returns 'ranked matches with similarity scores and task IDs' and is 'tolerant of typos, word reordering, and partial names.' This explains matching semantics without contradicting the annotation.

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, each earning its place: purpose, usage timing, and matching tolerance. Information is front-loaded and there is no filler, repetition, or vague language. It is both concise and information-dense.

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 core workflow, result type, and matching behavior. With a fully self-documenting schema, readOnlyHint annotation, and an output schema present, nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and each parameter already has a detailed description (e.g., minScore explains raising/lowering thresholds). The tool description adds marginal value by framing the name parameter as 'the task name you are about to create' and mentioning tolerance behaviors, but it does not need to restate schema information.

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

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

The description opens with a specific verb and resource: 'Find existing OmniFocus tasks whose names are similar to a proposed new task name.' It clearly identifies the tool's purpose and distinguishes it from general search or filter tools by focusing on similarity matching and duplicate prevention. The workflow context ('Run this BEFORE creating a task...') further differentiates it from creation and editing siblings.

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

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

The description gives explicit when-to-use guidance: 'Run this BEFORE creating a task that might already exist' and explains the goal of reusing an existing task to avoid duplicates. It does not name specific alternative tools or give exclusions, but the context is clear enough for an agent to route to this tool during task creation.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds a useful semantic distinction (custom perspectives vs tags) and mentions hierarchical tree display, but this largely overlaps with schema parameter descriptions and does not disclose deeper behavioral traits such as error handling, truncation behavior, or response structure beyond what the schema already provides.

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 earning its place: the action, the when-to-use guidance, and the tree-display capability. It is front-loaded with the core purpose and contains no filler or repetition.

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

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

The tool has 6 parameters all documented in the schema, an output schema, and a readOnly annotation. The description adds the key use-case context and the critical distinction from tags. It is slightly incomplete in not pointing to list_custom_perspectives for discovering perspective names, but that is a minor gap given the rich schema.

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

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

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description reinforces the meaning of perspectiveName with examples and the 'NOT tags' distinction, but it does not add additional parameter-level semantics beyond that. 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 states a clear verb+resource pair: 'Get tasks from a specific OmniFocus custom perspective by name.' It differentiates itself from tag-based tools by explicitly saying 'NOT tags' and providing concrete example perspective names, making it easy for an agent to distinguish from siblings like get_tasks_by_tag.

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

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

The description gives explicit when-to-use guidance: 'Use this when user refers to perspective names like 'Today', 'Weekly Review', 'This Week' etc.' It also gives a when-not signal by clarifying these are not tags. However, it does not explicitly name an alternative tool (e.g., get_tasks_by_tag or list_custom_perspectives), so it stops short of a perfect 5.

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

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

Annotations already declare readOnlyHint=true, covering the read-only nature. The description adds no extra behavioral context beyond that—no mention of default hideCompleted behavior or that without a filter it returns all flagged tasks. It does not contradict 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 a single concise sentence that front-loads the core action. It contains no filler, though it could arguably include a note about the default hideCompleted behavior without becoming verbose.

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 simple tool with only two optional parameters and a read-only annotation, the description is adequate but sparse. It doesn't mention that without a project filter all flagged tasks are returned, or any limitations. The output schema exists, so return details are not required, but a bit more context would improve completeness.

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

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

The schema description coverage is 100%, with both parameters already documented. The description's phrase 'optional project filtering' adds minimal value beyond the schema's parameter description for projectFilter. Baseline of 3 is appropriate since the schema carries the parameter meaning.

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 verb and resource ('Get flagged tasks') and mentions optional project filtering, which is clear. However, it does not explicitly distinguish itself from sibling tools like filter_tasks or get_tasks_by_tag, though the resource 'flagged tasks' is specific 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?

No guidance is provided on when to use this tool versus alternatives. With many sibling tools offering overlapping task-listing capabilities (e.g., filter_tasks, get_forecast_tasks, get_inbox_tasks), the description leaves the agent to infer the appropriate 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, covering safety and scope. The description adds that the tool returns projects and subfolders, which is useful context beyond annotations. However, it does not disclose any potential details like depth of recursion, performance implications, or whether it returns only immediate children or all descendants. Since annotations cover the main safety aspect, a 3 is appropriate with some additional value from the description.

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 sentence that is direct and efficient, with no filler. It is appropriately concise and front-loads the action and resource, making it immediately comprehensible.

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 it is a read-only operation with a single parameter, well-covered schema, and an output schema present (though not analyzed), the description provides the essential context: what it returns (details, projects, subfolders). It does not explicitly mention the output schema, but since the output schema exists, the description doesn't need to explain return values in detail. Minor gap: deeper behavioral details like depth of subfolders are absent, but for a simple lookup tool, this is sufficient.

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

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

Schema coverage is 100%: the only parameter 'name_or_id' is described as 'Folder name or ID to look up', which is clear. The description adds minimal semantic value beyond this, since it doesn't clarify whether the ID is a database ID or an OmniFocus identifier, or how to distinguish a name from an ID. But with full coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Get details') and the resource ('an OmniFocus folder'), and specifies the scope ('including its projects and subfolders'). This distinguishes it from sibling tools like 'list_folders' (which lists folders) and 'get_project_counts' (which counts projects), making its 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 implies it is for retrieving a single folder's details, contrasting with list_folders for listing all, but it does not explicitly state when to use this tool versus alternatives like search_projects or list_projects. There is no mention of when not to use it or direct comparison to siblings, so the usage context is only implied rather than explicit.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so the agent already knows this is a safe read operation. The description adds only the forecast-scope context; richer behavioral nuances (e.g., 'Overdue tasks are always included', dateMode semantics) live in the schema parameter descriptions, not the tool description. No contradictions found.

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, front-loaded sentence with no filler. It states the resource and the core filter in a compact parenthetical, which is exactly as concise as it needs to be.

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 itself is minimal, but the input schema thoroughly documents every parameter, an output schema exists, and annotations cover the read-only safety profile. The only gap is the lack of explicit sibling-tool routing, but that's a usage-guidance concern rather than a completeness 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?

The input schema has 100% description coverage for all five parameters, including defaults and edge cases. The tool description adds no parameter-level meaning beyond what the schema already provides, 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 uses a specific verb ('Get') and resource ('tasks from OmniFocus forecast perspective'), and clarifies the scope with 'due/deferred tasks in date range'. This clearly distinguishes it from siblings like get_flagged_tasks or get_inbox_tasks, even without reading 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 description implies the use case—retrieving forecast tasks—but provides no explicit guidance on when to prefer it over alternatives like get_custom_perspective_tasks or get_today_completed_tasks. There is no 'when not to use' or mention of sibling 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?

The annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds no further behavioral context, such as how the inbox perspective is defined, whether it includes project tasks or only loose tasks, or any rate limits or side effects. With annotations covering the safety profile, the description adds minimal extra value, making a 3 appropriate.

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 concise sentence with no filler. It is front-loaded with the core action and resource. Every word earns its place, and there is nothing unnecessary.

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-only tool with one parameter and an output schema (which is present but not shown in the description), the description is sufficiently complete for calling the tool. The agent knows what it does and how to use the parameter. The only gap is the absence of usage guidance, but that falls under dimension 2 rather than completeness for a single 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?

The single parameter hideCompleted is fully documented in the input schema with its meaning and default. Schema coverage is 100%, and the description does not add any additional semantics beyond what the schema provides. Baseline for high coverage is 3, and there is no extra value added.

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 and resource: 'Get tasks from OmniFocus inbox perspective.' It clearly identifies the action and the specific perspective. However, it doesn't differentiate from sibling tools like get_flagged_tasks or get_forecast_tasks, which follow a similar pattern, so it's clear but not distinct.

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. There is no mention of other inbox-related perspectives, no exclusions, and no context about prerequisites or typical use cases. Agents are left to infer that this is the tool for the inbox perspective among many similar get-* tools.

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

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

Annotations already declare readOnlyHint=true ben openWorldHint=false, covering the safety profile. The description adds no additional behavioral details such as pagination, empty results, or error behavior, but for a simple aggregate read operation with an output schema, this is acceptable.

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 that front-loads the primary operation and the key grouping dimension. No filler or redundant elaboration.

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 aggregate-read tool with one optional parameter, full schema coverage, readOnlyHint, and an output schema, the description conveys everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100% and the parameter description already explains that folder is an optional scope. The tool description adds no extra meaning beyond what the schema provides, matching the baseline of 3.

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

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

Description states a specific verb ('Get') with a clear resource ('aggregate project counts') and the dimension by which counts are grouped (status). It clearly distinguishes itself from list_projects and get_task_counts by focusing on status-based aggregate counts.

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

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

The description implies the tool is for retrieving aggregate status counts, with an optional folder scope, which provides clear context for when to use it. However, it does not explicitly mention when not to use it or name alternatives like list_projects for detailed project data.

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 annotation readOnlyHint=true already signals a safe read operation, so the description does not need to repeat that. The description adds that retrieval can be by ID or name, which is a behavioral nuance beyond the schema. It also implies a single task result, which is helpful context. No contradictions.

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

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

The description is a single, short sentence that directly states the tool's purpose and the two ways to specify the task (ID or name). There is no fluff, and the key 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?

The tool is simple: two optional parameters, both fully described in the schema, and an output schema exists (implicitly providing return structure). The description covers the core selection logic. It would be slightly better if it mentioned the exclusivity of the two params or fallback behavior, but given the available structured information, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description restates what the schema says (ID or name) but does not add new meaning such as format requirements, mutual exclusivity, or which is preferred. Baseline of 3 is appropriate given full schema coverage.

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

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

The description states a specific verb ('Get') and resource ('information about a specific task') and indicates retrieval by ID or name. It is clear what the tool does, though it does not explicitly differentiate from siblings like 'get_task_counts' or 'find_similar_tasks'.

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

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

The description implies the tool is for fetching a single task by ID or name, but it does not state when to use this versus other retrieval tools (e.g., filter_tasks, get_tasks_by_tag) or mention any prerequisites or limitations (e.g., exactly one of taskId or taskName must be provided).

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 this as read-only (readOnlyHint=true) and closed-world (openWorldHint=false), so no destructive-behavior disclosure is needed. The description adds a useful summary of the metric categories (total, available, completed, etc.) but doesn't go beyond that into quirks such as default exclusions or date-mode 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?

Two tight sentences, front-loaded with the operation and followed by the output categories; every phrase 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 aggregate tool with a complete schema and an output schema available, the description is sufficient for selection and invocation. It captures the essential filters and return categories, though it doesn't spell out default behavior (e.g., includeProjectRoots) or dateMode semantics—those are already encoded in the schema.

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

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

Schema coverage is 100%, with each of the seven parameters documented inline, so the baseline is 3. The description merely names filter dimensions already in the schema and adds no format, default, or interaction detail beyond it.

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

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

The description opens with a specific verb and object ('Get aggregate task counts') and enumerates the available filter dimensions and returned metrics, so an agent immediately understands the deliverable. It doesn't explicitly contrast with siblings such as get_project_counts or filter_tasks, but the 'task counts' resource and aggregated nature are 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?

There is no guidance on when to choose this over filter_tasks, get_flagged_tasks, or get_tasks_by_tag; the description states only what the tool does, not when alternatives are more appropriate. The optional-filters phrase implies a counting use case, but no exclusions or alternative routing are provided.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the context that tags are labels assigned to individual tasks, which clarifies the domain but does not disclose additional behavioral traits such as pagination, result limits, or any edge cases. Given the annotations, the description provides minimal extra behavioral value beyond what the schema and annotations already imply.

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

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

The description is two sentences, front-loaded with the core purpose and usage guidance, with no redundant information. Every word contributes to clarity.

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 are covered. The description gives enough context to understand the tool's purpose and usage, including the distinction from custom perspectives. It does not mention when to use filter_tasks as an alternative, but the primary usage guidance is sufficient for most cases. The definition is adequate for a read-only filtering tool with three parameters.

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 all three parameters (tagName, exactMatch, hideCompleted) are documented in the schema. The description does not add any additional meaning or clarifications about the parameters beyond what the schema already provides, so it meets the baseline of 3.

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

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

The description states a specific verb ('Get'), resource ('tasks'), and filtering criteria ('by OmniFocus tags'), and explicitly distinguishes from custom perspective names. This makes it clear what the tool does and differentiates it from sibling tools like get_custom_perspective_tasks.

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

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

The description explicitly says 'Use this for tag-based filtering, NOT for custom perspective names,' providing a clear when-to-use directive and an exclusion. This directly guides the agent away from inappropriate 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 declare readOnlyHint=true, so the description carries less burden. However, the description adds only the mild framing 'view today's accomplishments' and does not disclose any additional behavioral traits such as response format, pagination, or sorting. It adds minimal value beyond the annotations.

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

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

The description is a single concise sentence that front-loads the action. The second clause 'view today's accomplishments' is slightly redundant with the first, but overall the description is efficient and avoids unnecessary verbosity.

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 tool with one optional parameter and an existing output schema (per context signals), the description is minimally adequate. It clearly states the purpose, and the annotations cover the read-only nature. However, it lacks usage context or clarification on how it differs from other task-list requests, leaving the agent to infer when to use it.

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 covers the single parameter 'limit' with a description at 100% coverage. The tool description does not mention the limit parameter, so it adds no extra meaning beyond the schema. Per the baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the verb 'get' and the resource 'tasks completed today', making the purpose unambiguous. It is specific enough to distinguish from siblings by name and scope (completed today), though it does not explicitly contrast with other task-listing tools like get_inbox_tasks or get_forecast_tasks.

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

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

The description provides no guidance on when to use this tool versus alternatives. It simply states what it does but gives no context about when an agent should prefer it over other task-list tools, nor does it mention any exclusions or conditions.

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

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

Annotations already provide the safety profile with readOnlyHint=true and openWorldHint=false. The description adds the conditional behavior that includeRules expands results with filter rules and aggregation, which is useful. It does not contradict annotations, and it adds modest value beyond them.

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

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

Two concise sentences with the core action first and the optional behavior second. There is no filler, redundancy, or unnecessary 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 simple read-only enumeration tool with an output schema and fully documented optional parameters, the description plus structured fields is complete. An agent has enough information to call it correctly without missing prerequisites or hidden behavior.

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 each parameter already has a clear structured description. The tool description adds little beyond what the schema states, especially for fresh and format. The includeRules mention is helpful but largely duplicates the schema text.

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: 'List all custom perspectives defined in OmniFocus.' It also names the optional behavior around includeRules, which adds precision. It is distinct from task-focused siblings like get_custom_perspective_tasks, but it does not explicitly call out sibling differentiation, so it stops short of a 5.

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: the tool is the obvious way to enumerate custom perspectives, and the sentence about includeRules gives a direct usage condition. However, it does not name alternatives such as get_custom_perspective_tasks or update_perspective_rules, nor does it state 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?

The description adds useful behavior beyond the annotations: it lists all folders and includes project counts in the result. The readOnlyHint already covers safety, and there is no contradiction with 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 one short sentence with no filler and front-loads the action and target resource. Every word contributes to understanding what the tool does.

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-only list operation, the description, annotations, input schema, and output schema together provide everything an agent needs. Nothing essential is missing for selecting or invoking the tool correctly.

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

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

The input schema has 100% description coverage for both parameters, so the schema carries the parameter-documentation burden. The tool description itself adds no parameter-level meaning, which matches the baseline of 3.

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

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

The description names a specific verb ('List') and resource ('OmniFocus folders') and adds the scope qualifier 'all'. The project-count detail further distinguishes it from siblings like get_folder and list_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?

The usage is implied by the resource name: an agent can reasonably infer this is the folder-listing tool. However, the description does not explicitly state when to prefer it over get_folder, list_projects, or get_project_counts, nor does it 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description does not need to restate safety. It adds the useful clarification that notifications are reminders, but does not describe return format, ordering, or behavior when no parameters are given. Value is modest given the annotation coverage.

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

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

The description is a single, front-loaded sentence that conveys the action and scope without any filler. It is concise and immediately understandable.

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 straightforward read-only list operation with an output schema and two optional, well-documented parameters, the description is adequate. It does not explain the case where neither parameter is provided, but the schema implies at least one is needed, and the overall tool is simple.

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

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

Schema coverage is 100% with descriptions for both parameters, so the description adds no new meaning beyond what the schema already provides. It does not clarify that taskId and taskName are alternatives or which one to use, but the schema itself notes taskName is an alternative.

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 'all notifications (reminders)' scoped to a task. It distinguishes itself from sibling add_notification and remove_notification tools by purpose, leaving no ambiguity about what operation this 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?

While this is the only list-notifications tool among siblings, the description gives no explicit guidance on when to use it or which parameter (taskId vs taskName) to prefer. The use case is implied rather than stated, and no exclusions or alternatives are mentioned.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds behavioral context by mentioning filtering, sorting, and pagination, and the schema adds cache-bypass semantics via the 'fresh' parameter. The description itself doesn't add much beyond the schema, but the combination of annotations and schema covers behavior well. A 4 is justified because the description plus structured data give a clear behavioral picture without contradiction.

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

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

One sentence, front-loaded with the core action and resource, then the filter dimensions. Zero waste. 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 list tool with a rich output schema, 100% parameter coverage, and readOnlyHint annotation, the description is nearly complete. The only minor gap is that it doesn't explicitly state the default sort order or that all parameters are optional, but the schema already covers those. A 4 is appropriate because the description plus structured data leave little 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 100%, so the schema already documents all 9 parameters thoroughly, including defaults, enums, and date-time semantics. The description adds no parameter-level detail beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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 verb ('List and filter'), a clear resource ('OmniFocus projects'), and enumerates the exact filter dimensions (folder, status, stalled state) plus sorting and pagination. This distinguishes it from siblings like search_projects and get_project_counts without needing to open schemas.

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 when to use this tool: when you need a paginated, filterable list of projects. It does not explicitly name alternatives or exclusion conditions (e.g., 'use search_projects for text search'), but the filter dimensions and pagination signal the intended use case clearly. A 4 is appropriate because context is clear but exclusions are 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=true, so the read-only nature is covered. The description adds the recursive option and the notion of showing 'full hierarchy', which gives an agent insight into the tool's behavior beyond the schema annotation. It does not contradict 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?

A single, front-loaded sentence that states the verb, resource, and key optional behavior without any filler. Every word contributes to the tool's purpose and usage.

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 low-complexity read-only tool with no required parameters, an output schema, and full parameter descriptions, the description is sufficient. An agent can correctly invoke the tool and understand its behavior without additional context.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description mentions 'recursive' in a way that aligns with the schema's default and meaning, but does not add information beyond what the schema already provides. 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 states a specific verb ('List'), a concrete resource ('children (subtasks) of a task'), and adds the optional recursive behavior. This clearly differentiates it from siblings like get_task_by_id or filter_tasks, which focus on individual tasks or broad filtering rather than parent-child hierarchy.

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 a clear context: use this when you need to list subtasks of a given task. It does not explicitly name alternatives or state when not to use it, but the purpose is specific enough that the intended usage is unambiguous. No exclusions are mentioned, but the context is clear.

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

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

Annotations already declare readOnlyHint=trueverse, and the description adds only modest behavioral context: output includes task counts and results can be filtered by status. It does not contradict the annotations and does not need to disclose mutation behavior, but it also does not describe defaults, cache behavior, or other operational traits beyond what the schema already provides.

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, front-loaded sentence with no filler. It conveys the operation, resource, result content, and a filtering option 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 a complete input schema, readOnlyHint, and an output schema present, the description is sufficient for an agent to invoke the tool correctly. There are no required parameterscars, and the description covers the essential behavior of listing tags with counts and status filtering.

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%; all four parameters have descriptions and the key enums are defined. The description only echoes the status filter and adds nothing beyond the schema for fresh, limit, or sortBy, so the 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 uses a specific verb and resource: 'List all OmniFocus tags' and adds meaningful result details ('with available task counts') and a filtering dimension ('filterable by status'). This clearly distinguishes it from siblings such as search_tags, create_tag, or get_task_counts.

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 prefer list_tags over alternatives like search_tags or get_tasks_by_tag, and no exclusions or prerequisites are mentioned. The sentence states the tool's purpose, not the decision 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?

Beyond the annotations (destructiveHint true, readOnlyHint false), the description discloses key runtime behaviors: 'read' returns small files inline as base64 and writes larger ones to an absolute savePath, 'add' accepts either base64 or filePath, and there is a 10MB limit. This adds practical detail about output and input handling that is not present in 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 exactly two sentences, front-loads the core purpose and operation list, and packs in the most relevant behavioral details (inline vs. file, base64 vs. path, 10MB limit) without redundancy. 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?

Given the presence of an output schema (which covers return values) and a fully documented input schema, the description covers the essential operational context: what operations exist, how input is provided, and size constraints. It does not mention edge cases like re-listing after removal, but that is already in the index parameter description, so the description is complete for an agent to call the tool correctly.

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

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

The schema provides 100% coverage, so every parameter already has a meaningful description. The tool description adds a high-level summary of the operations and the 10MB limit, but it does not introduce semantics beyond what the schema already states (e.g., the 262144-byte threshold for savePath is in the schema). This matches the baseline for high schema coverage.

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

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

The description clearly states the verb 'manage' and the resource 'file attachments on a task or project', then enumerates the four specific operations (list, read, add, remove). This distinguishes it from sibling tools that handle tasks, projects, or notes, and leaves no ambiguity about its scope.

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

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

The description implicitly defines when to use this tool—any time file attachments need to be handled on a task or project—and the operation field further clarifies the use case for each action. It does not explicitly name alternatives, but the sibling set contains no other attachment-specific tool, so the usage context is clear and 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 declare destructiveHint=true and readOnlyHint=false, lowering the burden. The description adds meaningful behavioral context by stating that mark_reviewed stamps projects and advances next review dates, and that set_schedule changes intervals. It does not contradict the annotations, though it could more explicitly warn that set_schedule overwrites existing schedules.

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 dense paragraph organized by operation, with the workflow label front-loaded and no filler. It earns a 4 rather than 5 because the packed semicolon-heavy structure requires careful reading, though it remains efficient.

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

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

The schema is rich, covering all parameters, constraints, and mutual exclusions, and an output schema exists, so the description only needs to provide operation-level orientation, which it does. The only notable gap is not explicitly stating that mutating operations are destructive, but the annotation already supplies that signal.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds operation-level grouping of parameters like all, projectIds, and unit/steps, but it largely restates the schema's own descriptions rather than adding genuinely new 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 names a specific workflow and enumerates three distinct operations with concrete verbs and resources: list_due, mark_reviewed, and set_schedule. This clearly distinguishes the tool from generic project-management siblings and from the title alone.

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 maps each operation to its intended task: listing due reviews, marking projects reviewed while advancing schedules, and setting review intervals. It does not name alternatives or exclusions relative to sibling tools, but the operation-level routing is clear and sufficient for the review workflow.

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