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

With no annotations, the description discloses side effects (may bring to foreground), idempotent nature, and return object shape. Could mention error handling but sufficient for a simple launch tool.

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

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

Two sentences covering purpose, usage constraints, return values, and side effects. No wasted words.

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

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

Given zero parameters and no output schema, the description fully explains return value and side effects. Complete for this tool's complexity.

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

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

No parameters exist, and the schema coverage is 100%. The description adds no parameter info, which is appropriate. Baseline 4 for zero-param tools.

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 the specific verb 'launch' and resource 'OmniFocus', clearly stating it explicitly launches the app. It distinguishes from siblings like app_window_new which manage windows within the app.

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

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

Explicitly states when to use (user explicitly asks) and when not to (prefer other tools when already running). Also notes idempotency.

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?

Since no annotations are provided, the description fully discloses behavioral traits: it is a UI-affecting tool only meaningful when OmniFocus is running, has no data cache invalidation, returns specific structure, and errors (WINDOW_OPEN_FAILED). This is comprehensive.

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

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

The description is well-structured with each sentence serving a purpose: action, constraints, usage guidance, return info, errors, side effects, and example. It is front-loaded with the core action and is appropriately sized for the information provided.

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

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

Given no parameters and no output schema, the description is complete: it covers purpose, constraints, return shape, errors, and side effects. No additional information is needed for an agent to use 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?

The description explicitly states 'Takes no arguments' and provides an example call with no parameters. With zero parameters and 100% schema coverage, the description adds clarity by confirming emptiness and showing usage.

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

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

The description clearly states it opens a new OmniFocus window via OmniJS, using a specific verb ('Open') and resource ('new window'). It distinguishes from sibling tools by explicitly stating it is UI-affecting and not for reading data, directing to task_list or project_list for data queries.

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

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

The description provides explicit when-to-use scenarios ('when the user asks open a new window' or 'flow needs a fresh, unfocused OmniFocus window') and when-not-to-use ('Headless agents should not fire this', 'Do NOT use to read task or project data'). It also suggests alternatives (task_list, project_list).

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

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

With no annotations, the description fully discloses side effects (opens a new tab, no data cache invalidation), possible errors (WINDOW_UNAVAILABLE, WINDOW_OPEN_FAILED), and return value shape. This exceeds transparency requirements.

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

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

The description is well-structured and front-loads the main purpose. It contains several sentences that each provide valuable context, but could be slightly more concise by combining some statements. Still, it is efficient and 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?

Given no parameters, no output schema, and no annotations, the description covers all necessary aspects: purpose, usage guidance, side effects, errors, and return format. It is fully complete for this simple tool.

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

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

The tool has no parameters, and schema coverage is 100% by default. The description adds nothing extra about parameters, but that is acceptable as there is nothing to add. Baseline 4 is appropriate.

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

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

The description clearly states the tool opens a new tab on the front OmniFocus window via OmniJS. It specifies the exact resource and action, and distinguishes itself from the sibling tool 'app_window_new' by explicitly stating not to use it for standalone windows.

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

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

The description provides explicit when-to-use scenarios ('when the user asks open a new tab or a flow needs an additional view'), warns headless agents not to fire it, and directs to an alternative ('prefer app_window_new instead') for standalone windows.

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

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

With no annotations, the description provides behavioral details: file is embedded into database, path scope and size caps, return shape including edge case (null if parent deleted), and sync_trigger requirement. Somewhat thorough for a deprecated tool.

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

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

Description is a single paragraph but efficiently conveys deprecation, purpose, constraints, and return value. No redundancy, but could be slightly more structured.

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

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

Given deprecation, the description covers enough for an agent to understand the tool's behavior, constraints, and output. The return shape is detailed. Completeness is high for a tool not intended for new use.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context on path scope and size cap but does not fully explain mutual exclusivity of taskId/projectId beyond schema. Adequate but not exceptional.

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

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

Clearly states the tool is deprecated and renamed to attachment_create. It specifies the action (adds a file attachment) and resource (task or project). Distinguishes from sibling attachment_create as the replacement.

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

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

Explicitly advises not to use this tool (DEPRECATED) and directs to use attachment_create instead. Provides clear when-not and alternative.

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

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

With no annotations, the description fully discloses behavioral traits: file is embedded into database, mutations do not propagate until sync_trigger, and return value behavior (ownerName null if parent deleted). Size cap and scope constraints are also transparent.

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 concise paragraph of 4-5 sentences, front-loading the core action and then adding essential details. It includes an example for clarity without being 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?

The description fully covers the tool's behavior, constraints, and return value structure. For a create tool with no output schema, it provides sufficient context for an agent to use 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 coverage is 100%, but the description adds critical constraints beyond the schema: that exactly one of taskId or projectId must be provided, and explains the path scope and size limitations. The example also clarifies usage.

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 'Add', the resource 'file attachment', and the target 'task or project'. It distinguishes from siblings like attachment_add (which is likely redundant? but the description explicitly says 'from a local file path', differentiating from other attachment tools).

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

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

The description provides important prerequisites: file path must be within allowed scope, file must not exceed size cap, and mutations require sync_trigger. However, it does not explicitly compare with alternatives like attachment_add or mention 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?

Without annotations, the description fully compensates by detailing the return format, the survival of ownerName even on failure, NotFound error, permanence, and the need for sync_trigger. This is comprehensive and exceeds expectations.

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

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

The description is well-structured with the main action first, followed by exclusions, return behavior, errors, permanence warning, sync note, and example. Although slightly long, each sentence serves a purpose.

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

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

Given no output schema, the description thoroughly covers return format, error behavior, side effects (permanence, sync requirement), and usage hints. It provides all necessary context for an agent to use 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?

The description adds value beyond the schema by stating that exactly one of taskId or projectId should be provided, and that attachmentId comes from attachment_list. It also provides an example call, which clarifies parameter usage.

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 'remove' and resource 'attachment' from a task or project. It distinguishes from attachment_save_to_path but not from the sibling attachment_remove, which could cause confusion for the AI 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 description explicitly advises against using for retrieval and recommends attachment_save_to_path as an alternative. It also warns about permanence. However, it does not address the existence of sibling attachment_remove, leaving 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?

No annotations are provided, but description discloses read-only nature ('Read-only; safe to retry') and return structure. Adds transparency beyond schema. Could mention pagination or limits if any, but current detail is sufficient for a list tool.

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

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

Three well-structured sentences: purpose, usage guideline, return format + requirement. Includes example without extra fluff. Every sentence adds value.

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

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

Without output schema, the description fully documents the return format (array of objects with fields) and usage example. Enough for an agent to invoke correctly. No missing 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 coverage is 100% and both parameters already have descriptions. The description adds critical constraint 'Provide exactly one of taskId or projectId' and includes an example usage, which helps avoid misuse.

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 has a specific verb 'List' and resource 'file attachments on a task or project'. It clearly distinguishes from sibling attachment_save_to_path by stating not for content retrieval. The return format is also specified.

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

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

Explicitly states when not to use ('Do not use to retrieve attachment content') and what alternative to use. Also provides usage condition: 'Provide exactly one of taskId or projectId'. Clear 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?

No annotations provided, so description carries full burden. Discloses return object structure, null ownerName scenario, error behavior (NotFound), permanence, and sync trigger requirement. Comprehensive.

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

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

Description is detailed but not unnecessarily long. Structured with purposeful sentences, though could be slightly more concise. Still earns its length with valuable 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?

No annotations or output schema, yet description covers all critical aspects: purpose, deprecation, input constraints, return value, error cases, side effects, and sync note. Fully complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline 3. Description adds context: attachmentId source (attachment_list) and the mutual exclusivity of taskId/projectId, but schema already describes that. No additional meaningful parameter details beyond schema.

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

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

Description clearly states the tool removes an attachment by ID, distinguishes from retrieval and from the renamed sibling (attachment_delete). Verb+resource+scope are precise.

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

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

Explicitly marks deprecated with replacement (attachment_delete), and warns against using for retrieval (use attachment_save_to_path). Provides clear when/when-not guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool writes/overwrites files, has no side effects on OmniFocus data, and returns a specific success object. It lacks details on error handling or permission checks, but overall provides sufficient behavioral context.

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

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

The description is concise: two sentences plus an example. It is front-loaded with the core purpose, then adds caveats and an example. Every sentence provides necessary information without redundancy.

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

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

Given the tool's simplicity (4 params, no output schema), the description covers purpose, usage constraints, parameter semantics, return value, and side effects. It is fully sufficient for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by including an example call, clarifying mutual exclusivity of taskId/projectId (though schema also mentions it), specifying that destPath must be absolute and overwrites, and noting that attachmentId comes from attachment_list. This extra context justifies a higher score.

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

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

The description clearly states the action: 'Copy an attachment's content to a local file path.' It also explicitly distinguishes from siblings by instructing not to use for listing or removing, and naming attachment_list and attachment_delete as alternatives.

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

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

The description provides explicit usage boundaries: 'Do not use to list or remove attachments — use attachment_list or attachment_delete instead.' It also specifies a constraint: 'Destination path must be within the allowed scope (default: $HOME).'

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

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

With no annotations, the description fully discloses read-only nature, token expiry (~10 min), reset flag meaning, delta format, and that deletions require a full scan.

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?

Dense information, front-loaded purpose, but slightly long; every sentence earns its place though.

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?

No output schema, but description fully specifies return structure (reset, syncToken, tasks/projects with added/modified/removed) and delta format.

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% but description adds context: syncToken for bootstrapping vs incremental, includeRemoved trade-off between performance and completeness.

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

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

Clearly states it's an incremental sync feed for changes since last call, distinguishing it from list/search tools among 100+ 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?

Explicitly covers bootstrapping vs incremental use, token handling, and when to use includeRemoved vs reconcile with task_list/project_list for deletions.

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?

Without annotations, the description fully discloses behavioral traits: token single-use, 5-minute expiry, error conditions (NotFound for expired/unknown tokens, InvalidInput for out-of-range choice), and the overall behavior of resuming the original tool call.

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 but covers all necessary information efficiently. It could be slightly more structured (e.g., bullet points), but the content is precise and front-loaded with the 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 no output schema, the description explains the return (final result envelope) and covers workflow, errors, and an example. For a 2-parameter tool, this is fully complete.

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

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

Schema coverage is 100% with descriptions, but the tool description adds crucial context: replayToken comes from the clarification-needed envelope, choice is a zero-based index matching ClarificationOption.index, and provides an example. This adds value beyond the schema.

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

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

The description clearly states the tool's role as a replay dispatcher for clarification-needed responses, explaining the interaction flow and distinguishing it from sibling tools by its specific function in disambiguation.

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

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

It explicitly states when to use the tool (after receiving a clarification-needed response) and provides context on token expiry and the need for promptness. However, it does not explicitly mention when not to use it, though the scenario is well-defined.

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

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

Discloses stack advancement, invalidation semantics, mandatory confirm pattern, side effects (read cache invalidation, no sync), and return value. With no annotations, description fully carries behavioral disclosure.

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

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

Reasonably concise (~100 words), front-loads key action and analogy. Each sentence adds value, though could be slightly trimmed without loss.

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

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

Covers purpose, when to use, behavioral traits, parameter semantics, side effects, and return value. No gaps given tool complexity and lack of annotations/output 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%, so baseline is 3. Description adds conflict acknowledgement reasoning and explicit rejection conditions, providing value beyond schema. Not extensive but sufficient.

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

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

Clearly states 'Re-apply the most recently undone mutation' with a UI analogy (⌘⇧Z in OmniFocus). Distinguishes from sibling database_undo by noting it's the direct counterpart and warns against using for specific operations.

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

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

Explicitly says when (as undo counterpart) and when not (for specific operations), mentions alternative database_undo, and notes sync_trigger for propagation. Provides clear context for appropriate use.

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

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

With no annotations, the description fully discloses side effects: reverts top of undo stack, invalidates read cache, does not trigger sync. It also explains the mandatory confirm flag's role in mirroring destructive-write patterns.

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 thorough but somewhat lengthy. It is well-structured with front-loaded purpose, mechanism, usage, side effects, and example. Minor redundancy could be trimmed, but overall effective.

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

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

Covers all essential aspects: purpose, parameter, usage guidelines, behavior, side effects, return value, and an example. No output schema needed as return is clearly described.

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

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

The single parameter 'confirm' is fully described in both schema and description. Description adds context about why it's mandatory and the behavior if absent, providing value beyond schema.

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

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

The description clearly states the tool reverses the most recent document mutation, analogizing it to ⌘Z in OmniFocus. It distinguishes from siblings like database_redo and specifies precise use cases.

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

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

Explicitly lists when to use (post-batch error recovery, retry-after-partial-failure cleanup, integration-test teardown) and when not to (rolling back specific operations). Also directs to sync_trigger for cross-device sync.

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

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

Discloses idempotency with return information, side effects (writes note, sets sync flag), and two possible return shapes. No annotations provided, so description covers all behavioral traits thoroughly.

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

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

Four sentences, each purposeful. Front-loads main action, then details idempotency, warning, returns, and side effects. No extraneous text.

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

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

For a simple tool with 2 parameters and no output schema, the description covers purpose, behavior, side effects, return format, and provides an example. Complete and 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% with clear descriptions. Description adds only an example and restates the enum, providing minimal extra value beyond schema.

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

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

Clearly states it clears a specific fenced block ('decision-journal') from a task or project's note, preserving other content. Distinguishes from deletion tools by explicitly warning not to use for deleting the target.

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

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

Explicitly says 'Do NOT use this to delete the target — prefer task_delete / project_delete', providing clear guidance on when not to use and 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?

The description fully discloses behavior: it writes a decision-journal fenced block to the target's note, preserves existing prose, notes side effects (writes via task_update/project_update, sets meta.syncPending), describes the return shape, and explains idempotency. With no annotations, it carries the full burden and does so comprehensively.

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

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

The description is appropriately sized and well-structured: starts with core purpose, then mechanism, usage caveats, idempotency, return, side effects, and an example. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (nested objects, side effects, idempotency, no output schema), the description covers all essential aspects: purpose, behavior, usage guidelines, parameters, idempotency, return shape, and side effects. An agent can correctly select and invoke this tool based on the description alone.

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, but the description adds significant value beyond the schema: it explains the purpose of each parameter in context (e.g., targetKind discriminates, decision payload details, idempotency_key for retry), mentions auto-set recordedAt, and provides an example. This enriches the understanding despite 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 'Record', the resource 'agent memory of user judgment', and the scope (task/project). It distinguishes from siblings by specifying it writes a 'decision-journal' fenced block, not a generic note, and contrasts with short-lived state tools like waiting-on and task_update.

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

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

Explicitly states when to use (for long-term decisions) and when not to use (for short-lived state, prefer waiting-on or task_update). Provides guidance on the idempotency_key for retry safety and discriminates on targetKind, giving clear usage 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?

With no annotations, the description carries the full burden. It discloses that the tool is 'safe to call repeatedly; no side effects' and describes the return format. It does not cover potential errors or permissions, but for a read-only export, this is good.

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 five sentences, well-structured, and front-loaded with the core purpose. Every sentence adds necessary information without repetition or fluff.

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

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

Given no output schema, the description adequately covers purpose, usage, parameters, and return format. It lacks details on error cases or what happens with invalid inputs, but overall is sufficient for a simple export tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by providing examples (e.g., export_opml({ scope: 'project', id: 'abc123' })) and clarifying that 'id' is required for specific scopes. This extra context justifies a 4.

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

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

The description explicitly states the tool exports OmniFocus data as OPML XML, a structured outline format. It distinguishes itself from siblings like export_taskpaper (different format) and import_opml (import vs export) by clearly defining its output format and scope levels.

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 clear when-to-use guidance: 'Do NOT use to export a single task; OPML scope is project-level or broader.' It also explains three scopes with examples. Missing explicit mention of alternative tools for single-task exports, but the warning is strong enough to guide proper usage.

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

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

Discloses lossy nature of export, lists downgraded/omitted items, mentions lossiness warnings in meta.warnings, and states no side effects. No annotations provided, so description carries full burden and does so well.

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

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

Concise at 5 sentences, front-loaded with main purpose, uses clear structure with quoted scopes and examples. No wasted words.

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

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

Given two simple parameters, no output schema, and sibling tools, description covers purpose, usage, behavior, parameters, and examples completely.

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%, but description adds value by explaining scopes in more detail (e.g., 'one project + its tasks') and providing usage examples. Enhances understanding beyond schema.

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

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

Clearly states it exports OmniFocus data as TaskPaper plain text with three scopes. Distinguishes from sibling tool import_taskpaper by explicitly saying not to use for import, and provides examples.

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

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

Explicitly describes when to use each scope, gives examples, and warns against using for import, directing to alternative. Also notes safe to call repeatedly with no side effects.

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

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

Discloses key behaviors: returns persistent ID, triggers sync. Suggests calling sync_trigger after. No annotation contradictions. Could mention uniqueness constraints, but sufficient for a create 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?

Four sentences covering purpose, optional nesting, negative guideline with alternative, return value and sync note. Includes examples. No wasted words.

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

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

Given 2 parameters (both described), no output schema, and sibling tools, the description covers purpose, usage, parameters, return value, and sync behavior. Lacks only minor details like uniqueness, but overall complete.

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

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

Schema coverage is 100%, baseline 3. Description adds context: parentId is optional for root-level, get IDs from folder_list. Examples further clarify usage. Adds meaning beyond schema.

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

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

Clearly states the verb 'Create' and resource 'a new folder in OmniFocus'. Distinguishes from sibling tools like folder_move by explicitly stating not to use this tool for moving.

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

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

Provides explicit when-to-use (creating new folders, optionally nesting) and when-not-to-use (moving folders, prefer folder_move). Also gives context on obtaining parent IDs from folder_list.

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

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

No annotations provided, so description carries full burden. States no side effects, read-only contract, returns { description, plannedChanges }. Lacks details on error handling or edge cases, but sufficient for a simple preview tool.

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

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

Multiple sentences but each adds value: purpose, exclusion, return info, side-effect claim, usage example. Front-loaded with main action. Could be slightly more concise but 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?

No output schema, but describes return structure. Explains relationship to folder_create. For a dry-run tool with simple parameters, this is complete enough. Lacks error handling but acceptable.

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 good descriptions. The description adds context of mapping to folder_create parameters but does not enhance meaning beyond what 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?

Clearly states it previews folder_create without changes, and explicitly distinguishes from the actual creation tool. Includes a warning not to use it for creating.

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

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

Explicitly tells when to use (dry-run), when not to use (use folder_create instead), and provides workflow guidance: pass same args, inspect plannedChanges, then call write tool.

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

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

With no annotations, the description fully discloses default error on non-empty, cascade behavior, irreversibility, sync trigger, and examples. 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?

Two well-structured paragraphs with examples, no extraneous information, each sentence contributes value.

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

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

Covers essential behavioral details and examples, but does not mention what the tool returns (e.g., success status). Minor gap for a simple delete tool.

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

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

Schema coverage is 100%, but description adds context beyond schema: for id it repeats, for cascade it explains default and error behavior. Adds value but schema already described parameters well.

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

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

The description clearly states it deletes a folder from OmniFocus, distinguishes from folder_update (rename) and folder_list, and explains default vs cascade behavior.

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

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

Explicitly says when to use (delete) and when not to use (archiving), provides alternative (folder_update), explains cascade option, and tells to get ID from folder_list and call sync_trigger after.

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?

Explicitly states 'No side effects: read-only by contract' and 'never mutates OmniFocus'. With no annotations, description fully discloses behavior.

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

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

Three sentences, front-loads key purpose, no fluff. Each sentence adds value.

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

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

Covers purpose, usage, behavior, return value (description and plannedChanges), and relationship to sibling. No output schema, but description compensates.

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. Description mentions 'pass the same args' but does not elaborate on individual parameters beyond schema.

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

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

Description clearly states it previews folder deletion without changes, distinguishing from folder_delete. Uses 'preview', 'dry-run', and explicitly says 'Do NOT use to actually delete'.

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

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

Explicitly instructs when to use (dry-run) and when not (actual deletion), directing to folder_delete instead. Provides clear example of workflow.

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

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

No annotations are provided, so the description carries the full burden. It states 'Safe to call repeatedly; no side effects,' which is good. However, it does not disclose behavior for invalid IDs or potential errors, and could mention whether the folder must exist.

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

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

Three sentences plus an example, front-loaded with purpose. Every sentence adds value—usage guidance, return fields, safety, and a concrete example. No unnecessary words.

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

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

For a simple get-by-ID tool with no output schema, the description covers purpose, usage, parameters, return fields, and safety. It is complete enough for an AI agent to select and invoke correctly, especially given the rich context from sibling tools.

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% (both params described). The description adds significant meaning: for `id`, it explains how to obtain it (`Get from folder_list`) and stability; for `verbose`, it explains the effect on output shape and references documentation. This goes well beyond the schema alone.

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 'Fetch a single folder by its persistent ID'—a specific verb and resource. It explicitly distinguishes itself from the sibling tool `folder_list` by warning 'Do not use to list multiple folders; prefer folder_list instead.'

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

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

The description provides explicit when-to-use ('Fetch a single folder') and when-not-to-use ('Do not use to list multiple folders') guidance, and names the alternative (`folder_list`). It also adds context that the tool includes counts and is safe to call repeatedly.

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

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

No annotations provided, so description carries full burden. It states 'Safe to call repeatedly; no side effects' and describes return shape (flat array with projectCount and subfolderCount). Good but could mention more about potential performance or limits.

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

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

Description is well-structured with front-loaded purpose, but includes examples which are helpful. Could be slightly more concise, but every sentence adds value.

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

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

Given no output schema, description explains return format. Parameters fully covered with examples. Tool is simple (2 optional params) and description provides sufficient guidance 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?

Both parameters have schema descriptions (100% coverage). Description adds usage context: parentId for walking hierarchy, verbose for full shape, and provides examples. Excellent clarity beyond schema.

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

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

Description clearly states 'List folders in OmniFocus' with optional filtering by parent folder, and explicitly distinguishes from folder_get by warning against using it for a single 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?

Provides explicit when-to-use (listing folders, optionally filtered) and when-not-to (for single folder, use folder_get). Also advises using parentId to walk hierarchy one level at a time, but does not cover all potential contexts.

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

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

No annotations are provided, so description carries full burden. It discloses triggers a sync, returns updated folder's ID and new parentId, and gives examples. Lacks mention of potential failures or authorization, but is generally transparent.

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

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

Concise 5-sentence description with examples, front-loaded, no wasted words. Clear structure: purpose, usage, alternatives, return, examples.

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

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

Covers purpose, usage, return value, and follow-up action (sync_trigger). Adequate given simple parameters and no output schema; returns described.

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

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

Schema coverage is 100% with descriptions. Description adds context: 'id' from folder_list, 'parentId' can be null for root promotion, enhancing schema info.

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

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

The description clearly states 'Move a folder to a new parent, or promote it to a root folder', using specific action verbs and distinguishing from folder_update (rename). It also mentions promoting by passing parentId=null.

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

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

Explicitly states when to use (moving, promoting to root), when not to (rename), and directs to folder_update instead. Also instructs to get IDs from folder_list and to call sync_trigger afterward.

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

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

Declares 'No side effects: read-only by contract — never mutates OmniFocus' and describes return format { description, plannedChanges }, ensuring full transparency without 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 front-loaded with purpose, includes usage guidance and return info. Slightly redundant example line, but overall clear and concise.

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

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

Given no output schema, description adequately explains return structure ({ description, plannedChanges }) and tool's role as dry-run companion, covering all needed 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 covers 100% of parameters with descriptions, so baseline is 3. Description mentions 'pass the same args you would to the write tool' but adds no new semantics beyond schema.

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

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

Explicitly states 'Preview what folder_move would do without making any changes' and distinguishes from sibling folder_move by saying 'Do NOT use to actually move a folder — use folder_move instead.'

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

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

Provides clear when-to-use guidance as a dry-run companion before the write tool, explicitly warns against using for actual moves, and instructs to pass same args, inspect plannedChanges, then call write tool.

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

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

With no annotations, the description fully discloses the partial patch behavior and sync trigger side-effect. It is transparent about the mutation and required follow-up. Missing only potential permission requirements, but not essential for transparency.

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

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

The description is very concise with a clear front-loaded purpose, efficient use of sentences, and a helpful example. Every sentence earns its place with no redundancy.

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

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

Given the tool's simplicity (2 params, no output schema), the description is fully complete: explains what it does, how to obtain required input, what it returns, and important side-effects. No gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds an example and context for the 'name' parameter but does not significantly enhance 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 'Rename a folder (partial patch — only supplied fields are changed)' with a specific verb and resource, and distinguishes from the sibling folder_move tool.

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

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

Explicitly mentions when to use an alternative ('To move a folder use folder_move instead'), how to get the folder ID from folder_list, and guides post-operation steps ('call sync_trigger after to propagate to other devices').

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

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

No annotations are provided, so the description carries full burden. It explicitly states 'No side effects: read-only by contract — never mutates OmniFocus' and describes the return value structure. This is transparent and honest.

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 (5 sentences) and well-structured: first sentence states purpose, second warns against misuse, third describes output, fourth declares safety, fifth gives usage pattern. No wasted words.

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

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

Given no output schema, the description explains the return format ({ description, plannedChanges }) and asserts read-only behavior. For a dry-run tool with no nested objects, this is complete and 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% with clear descriptions for id and name. The description adds a high-level usage hint ('pass the same args'), which is helpful but not essential. The schema already does a good job, so baseline 3 is adjusted upward modestly.

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

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

The description clearly states the tool's purpose: preview what folder_update would do without making changes. It distinguishes from the sibling tool folder_update by explicitly warning against using this tool for actual updates, and it explains the output shape.

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

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

The description provides explicit when-to-use (dry-run), when-not-to-use (do not update), and suggests an alternative (folder_update). It also advises passing the same arguments to both 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?

With no annotations, the description fully covers behavioral traits: no side effects, safe to call repeatedly, pagination behavior with cursor, response structure including byDate when days>1, and handling of maxOutputBytes truncation. No contradictions with annotations since none exist.

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

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

The description is well-structured, starting with purpose, then usage, parameter details, response format, and examples. It is front-loaded and informative, though slightly lengthy; could be more concise while retaining all key information.

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

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

Given 11 parameters, no output schema, and moderate complexity, the description covers the response structure (categories, byDate, pagination with cursor and hasMore), parameter behaviors (fields filtering, maxOutputBytes), and edge cases (cursor validation, field dropping). It feels complete for the tool's 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 coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining ergonomic vs exact date interfaces, default inclusion of all categories, and interplay between parameters (e.g., days>1 triggers byDate). This justifies a 4.

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 retrieves forecast-view tasks grouped by categories (overdue, dueToday, deferredToday, flagged) and explicitly distinguishes it from task_list for listing all tasks, providing specific use cases like 'what's on my plate today'.

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

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

The description explicitly states when to use (daily planning, multi-day queries) and when not (prefer task_list for listing all tasks). It also provides guidance on parameter choices (date/days vs from/to) and includes examples.

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

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

With no annotations, description fully carries transparency. Clearly states read-only, no side effects, safe to retry, and explains return structure including null cases. Also notes backend source ('Backed by OmniJS Database.forecastTag').

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?

Single, well-structured paragraph with no wasted words. Front-loaded with purpose, followed by usage, return info, and safety. Every sentence adds value.

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

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

Given zero parameters and no output schema, description fully covers behavior, return value with null handling, and distinguishes from siblings. No gaps remain for a simple read tool.

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

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

Tool has no parameters (0 params), so baseline is 4 per rubric. Description does not need to add parameter info since none exist. It adds value by explaining the return value structure.

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 uses specific verb 'Read' and identifies the resource as 'OmniFocus forecast-tag preference'. It distinguishes from sibling tools by explicitly stating 'Do NOT use to list tags in general — prefer tag_list' and implies difference from forecast_set_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?

Provides explicit when-to-use examples ('answer what tag is the user using as their daily agenda?') and when-not-to-use ('Do NOT use to list tags in general'). Also states read-only and safe to retry, guiding appropriate usage.

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

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

With no annotations, the description fully discloses behavior: read-only, no side effects, safe to retry. It details the greedy algorithm, ordering (flagged, dueDate, ID), and explains skipped[] reasons (no-estimate, exceeds-budget).

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 comprehensive but slightly verbose. It front-loads the purpose and usage, then covers behavior and examples. Each sentence is meaningful, but could be tightened slightly.

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

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

Given no output schema, the description explains the return structure (selected[], totalMinutes, skipped[]) and algorithm in detail. It covers all aspects needed for correct use: parameters, behavior, side effects, and examples. Very complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how parameters affect the algorithm, providing range limits, and including example calls. However, it doesn't add much beyond what the schema already provides for filter properties.

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

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

The description clearly states the tool's core function: 'Pack today's forecast tasks into a time budget.' It provides specific use cases (user asks 'I have N hours; what should I do?') and explicitly distinguishes from sibling tools like forecast_get and multi-day planning.

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 clear when-to-use guidance (budgeting tasks into a time window) and explicit when-not-to-use (full forecast, multi-day scheduling) with alternatives (forecast_get). It also explains how to use it with parameters and examples.

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

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

No annotations provided, so description carries full burden. It discloses side effects ('mutation; invalidates the forecast read cache'), errors ('NOT_FOUND'), and return value structure. Also mentions underlying implementation ('Backed by OmniJS Database.forecastTag').

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

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

Every sentence adds value: purpose, usage, parameters, returns, errors, side effects, examples. Front-loaded with the core action. Well-structured and efficient.

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

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

For a single-parameter mutation tool with no output schema, the description fully covers applicable context: usage, parameters, return format, errors, side effects, and examples. No gaps.

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

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

Schema coverage is 100%, but description adds context: explains the purpose of tagId (set with string, clear with null), gives examples, and describes what null does. Adds value beyond schema.

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

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

The description clearly states the action ('Set or clear the OmniFocus forecast-tag preference') with a specific verb and resource. It distinguishes itself from sibling tools like task_update by explicitly noting that this tool is not for adding tags to 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?

Provides explicit when-to-use context ('onboarding flows or context switches') and when-not-to-use ('Do NOT use to add tags to a task — prefer task_update'). Also explains how to use parameters (pass tagId as string or null).

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

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

Discloses round-trip matching logic (by ID, then by name), lossy behavior (preserved: due dates, defer dates, flagged; dropped: tags, notes, attachments, repetition), return format, orphan handling, and write nature. No annotations provided, so description carries full burden and does so comprehensively.

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

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

Description is dense but efficient; front-loaded with main purpose and structure. Every sentence adds value, though slight length could be trimmed slightly without losing content.

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

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

Covers all aspects: input format, matching, lossy fields, return structure (imported count, tasks array with id/name), orphan handling, and required follow-up sync trigger. No output schema exists, so description fully compensates.

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%, but description adds context: opml parameter notes 'Well-formed OPML XML string' and recommends using export_opml output; destinationProjectId explains override behavior and source for project ID. Adds meaning beyond schema's brief descriptions.

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

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

Description clearly states the action (import), resource (tasks from OPML string), and destination (OmniFocus). It specifies it parses OPML from export_opml and recreates hierarchy, distinguishing it from export_opml and import_taskpaper.

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

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

Explicitly warns against using for export ('Do NOT use to export data; prefer export_opml for that') and instructs to call sync_trigger after import to propagate changes. Also mentions when to omit destinationProjectId for matching by ID/name.

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

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

With no annotations, the description fully bears the burden. It discloses parsing behavior, project matching logic, automatic tag creation, and output structure. It also notes that orphan IDs are dropped and that writes occur. Some details like idempotency or error handling are missing, but the essential behavioral traits are covered.

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

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

The description is moderately sized and well-structured. It includes an example and practical notes. While every sentence adds value, it could be slightly more concise. The information is front-loaded with the primary 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 there is no output schema, the description thoroughly explains the return value structure ({ tasks, warnings }) and the behavior of orphan IDs. It also mentions the need for sync_trigger. For a tool of this complexity, the description is complete and provides sufficient context 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%, and the description adds meaning beyond the schema: it provides an example of the text format and explains the effect of targetProjectId (overrides headings). This additional context helps the agent understand parameter usage beyond the schema descriptions.

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

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

The description clearly states the tool imports tasks from TaskPaper text into OmniFocus. It specifies the verb (import), resource (tasks), and target (OmniFocus). It differentiates from the sibling export_taskpaper by explicitly advising against using for export.

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

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

The description provides clear usage guidance: when to import TaskPaper text, mentions project heading mapping and fallback to inbox, advises to call sync_trigger for propagation, and explicitly warns not to use for export. Could be slightly stronger by explicitly stating alternatives for other operations, but the sibling list provides 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?

With no annotations provided, the description fully discloses behavior: it is read-only ('Read-only; does NOT trigger TCC prompt'), explains null conditions for fields like lastSync, and details side-effect free nature. 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 long but well-structured, explaining each returned field systematically. Every sentence provides value, though some redundancy exists (e.g., 'Read-only; no side effects' repeated). Still, it remains focused and informative.

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

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

Given no output schema, the description comprehensively documents every field, including null states, data sources, and examples. It covers all necessary context for an AI agent to understand the tool's behavior and output.

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

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

The tool has zero parameters, so baseline score is 4. The description does not need to add parameter meaning as there are none.

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

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

The description explicitly states it returns a health snapshot of the server, and distinguishes from siblings by instructing not to use it for OmniFocus data, pointing to specific alternatives like task_list, project_list, sync_status.

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

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

Provides explicit guidance: 'Do NOT use this to read OmniFocus data — prefer task_list, project_list, sync_status, etc.' and mentions omnifocus_doctor for live checks, clearly indicating when to use this tool versus 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?

No annotations exist, so the description fully bears the burden. It discloses side effects (writes to OmniFocus, sets meta.syncPending = true), retry behavior via idempotency_key, and output structure. However, it does not mention authorization requirements or whether the operation is reversible, which would elevate transparency further.

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 but remains efficient. It front-loads the core purpose and then covers guidelines, side effects, output, and example. Could be improved by using bullet points or breaking into sections, but it is not overly 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 no output schema, the description appropriately explains the return value. It covers side effects and suggests sync_trigger for propagation. All four parameters are addressed. It could mention error conditions (e.g., target not found), but overall it is sufficiently complete for a mutation tool with idempotency handling.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the newline insertion behavior, the purpose of idempotency_key for retry safety, and the return structure. It also provides an example. This additional context justifies a 4.

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 'Append' and resource 'plain-text note on a task or project', and explicitly distinguishes from the sibling 'note_set' by saying 'Do not use to replace the note entirely; prefer note_set instead.' This makes the purpose specific and unambiguous.

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

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

The description provides explicit when-to-use ('Append text'), when-not-to-use (avoid for replacement, prefer note_set), and a specific use case for retry safety with idempotency_key. It also includes a clear example, offering complete guidance for correct invocation.

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

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

With no annotations, description fully discloses read-only nature, no side effects, return format (string or null), and safe repeated usage. Example clarifies parameter usage.

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

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

Extremely concise: two sentences plus an example. Purpose is front-loaded. Every sentence adds value without redundancy.

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

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

For a simple read tool with 2 params and no output schema, description covers purpose, usage, parameters, return value, and safety. No gaps remain.

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

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

Schema coverage is 100% (baseline 3). Description adds value by explaining targetKind and id roles with example and context, exceeding schema descriptions.

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

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

Description clearly states 'Read the plain-text note from a task or project' with a specific verb and resource. It distinguishes from sibling note_get_html by advising against use when formatting fidelity matters.

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

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

Provides explicit guidance on when to use (plain-text reading) and when to use alternative (note_get_html for formatting). Also notes safe repeated calling and no side effects. Lacks explicit 'do not use' scenarios but alternatives sufficiently inform.

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

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

With no annotations, the description carries the full burden. It explicitly states 'Safe to call repeatedly; no side effects.' and mentions a known limitation. This covers safety and idempotency, but does not discuss error cases or response behavior when IDs are invalid.

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

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

The description is moderately lengthy but well-structured with front-loaded purpose, then limitation, usage, alternative, and safety. Each sentence contributes uniquely, though it could be slightly more concise.

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 tool with two parameters and no output schema, the description is thorough: it explains return type, known limitations, usage instructions, alternative tool, and safety. Only minor aspects like error handling are missing, but overall it is complete.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds value by clarifying the relationship between targetKind and id (e.g., set targetKind to 'task' and provide a task ID) and includes a usage example, which supplements the schema.

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

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

The description clearly states it reads the HTML fragment from a task or project note. It specifies the return format ({ noteHtml } — an HTML string or null) and distinguishes from sibling tool note_get by noting its plain-text 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?

Provides explicit guidance on when to use this tool vs note_get: 'For plain-text access without formatting, use note_get instead.' It also explains how to set targetKind and id, and notes a known limitation about OmniFocus 4.x degredation.

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

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

No annotations present, so description fully covers behavior: overwrites entirely, clears with null, side effects (writes to OmniFocus, sets syncPending), and recommends sync_trigger for cross-device sync. Also details return structure.

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

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

Concise single paragraph, front-loaded with purpose, no fluff. Every sentence adds necessary 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?

Given 3 params and no output schema, description fully compensates by detailing return object, side effects, and usage example. No gaps.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining source of id (from task_list or project_list) and example call, surpassing schema details.

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 specifies verb 'Replace', resource 'note', and scope 'task or project'. It distinguishes from sibling note_append by directing to use that for additive updates.

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

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

Explicitly states when to use this tool (replace note) and when to use alternative (note_append for adding text). Provides usage note for clearing note with null.

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

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

Discloses overwrite behavior, HTML subset limitations, null clear, OmniFocus 4.x failure, return object details (including pre-fetched name), side effects (writes, syncPending), and need for sync_trigger. No annotations provided, so description carries full burden and meets it thoroughly.

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

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

Every sentence is informative and necessary. Front-loaded with purpose, then covers details, limitations, alternatives, return, side effects, and example. No fluff.

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

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

Comprehensive given no annotations or output schema: covers purpose, parameters, return, limitations, alternatives, side effects, and example. No gaps.

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

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

Adds context beyond schema: explains noteHtml null to clear, targetKind enum values, id source, and provides full example. Schema coverage is 100%, but description enriches understanding.

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

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

The description clearly states the verb 'Replace' and resource 'HTML fragment note on a task or project', making the purpose specific. It also distinguishes itself from sibling note_set (plain text).

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

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

Explicitly states when to use (HTML notes) and when not to (OmniFocus 4.x, plain text). Provides alternative (note_set) and example usage.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It states that the tool has no side effects and will not launch OmniFocus, which is critical for an agent to understand. It also describes the return format and that it probes health. However, it does not mention whether it makes network calls or requires specific permissions, but for a diagnostic tool, the provided details are sufficient.

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

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

The description is tightly written with no extraneous words. It starts with the core purpose, then gives usage guidance, return format, behavioral notes, and an example, all in 6 sentences. Every sentence provides essential information for the agent to correctly use the tool.

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 no parameters and no output schema, the description is complete. It explains the return structure, the logic of summary, and instructs to surface remediation verbatim. It also clarifies the no side effects and distinction from other tools. The only minor gap is not stating potential performance impacts, but overall it is sufficiently complete for an agent.

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

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

The tool has zero parameters, and the input schema is empty with 100% coverage. The description clarifies this by showing an example call with no arguments. According to the baseline guideline for 0 parameters, a score of 4 is appropriate since the description adds no further parameter information but is consistent with the schema.

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

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

The description explicitly states the tool's purpose as a self-diagnostic for omnifocus-mcp setup, probing server health and OmniFocus connection. It distinguishes itself from the sibling tool 'internal_status' by specifying its use for triage when other tools fail, and from 'app_launch' by clarifying it does not launch OmniFocus. The verb 'probes' and resource 'server health and live OmniFocus connection' are specific and clear.

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 guidance on when to use this tool: 'only use to triage why another tool is failing.' It also explicitly advises against using it as a substitute for the actual work tool and recommends preferring 'internal_status' when only server metrics are needed. This direct comparison with a sibling tool gives the agent a clear decision criterion.

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

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

With no annotations, the description fully discloses behavior: JXA make for shell, OmniJS for rules/aggregation/iconColor, rollback on failure, side effects (invalidate cache, set syncPending), return value, and prerequisite (Pro).

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 comprehensive yet well-structured: purpose, creation process, usage, rule details, return, side effects, requirements, example. Every sentence adds value without redundancy.

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

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

For a tool with 4 parameters, nested objects, and no output schema, the description covers all essential aspects: purpose, input constraints, behavior, error handling, side effects, return value, and prerequisites. No gaps.

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

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

Schema coverage is 100%. Description adds significant meaning: explains rules shape matches perspective_get, constrains atoms to one action* predicate, describes aggregate and disabled wrappers, and gives an example. Provides context beyond schema.

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

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

The description clearly states the tool creates a new custom OmniFocus perspective with name, optional rules, aggregation, and icon color. It distinguishes itself from update and delete siblings, and explains its role in authoring flows.

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

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

Provides explicit when-to-use guidance: pair with perspective_get to clone or perspective_delete to replace, and do not use for updates (prefer perspective_update). Also notes the OmniFocus Pro requirement.

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

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

Despite no annotations, the description fully discloses side effects (writes to OmniFocus, removes perspective, sets meta.syncPending=true), permanence (no undo), return value ({ id }), and error conditions (validation error for built-ins, OF_FEATURE_REQUIRES_PRO without Pro).

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

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

The description is appropriately sized, front-loaded with the primary action, followed by usage conditions, side effects, and an example. Every sentence contributes valuable information without redundancy.

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

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

Covers all necessary aspects: what is deleted, prerequisites, error scenarios, side effects, return format, and even a recommended follow-up action (sync_trigger). No gaps given the tool's complexity and lack of output 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?

With 100% schema coverage, the description adds significant meaning: how to obtain a valid perspectiveId (from perspective_list, looking for kind 'custom'), notes that built-in ids are rejected, and provides an example call.

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

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

The description clearly states it deletes a custom OmniFocus perspective by id, distinguishing it from other tools like perspective_create or perspective_update. The verb 'delete' and resource 'custom perspective' are specific, and it explicitly notes it does not apply to built-in perspectives.

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

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

Provides explicit when-to-use ('cleaning up after a templated workflow, or rotating out a stale view') and when-not-to-use (built-in perspectives, which cannot be deleted). Also mentions preconditions (requires OmniFocus Pro) and recommends confirming with the user and using sync_trigger after deletion.

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

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

No annotations provided, so description fully covers behavioral aspects: read-only, no side effects, cursor pagination with defaults, error handling for Pro requirement, special handling for 'review' and 'nearby' returning empty arrays.

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

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

Well-structured with front-loaded purpose, but slightly lengthy. Could be condensed while retaining all essential information. Still highly informative and well-organized.

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

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

Comprehensive coverage for a list tool: explains return structure (tasks array), pagination details, error codes, special case return values, and provides examples. Despite no output schema, description 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 coverage is 100%, but description adds significant value: explains limit and cursor pagination behavior, lists allowed fields and their behavior (unknown dropped, warnings), provides examples and clarifies perspectiveId types.

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

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

Clearly states the verb 'evaluate' and resource 'OmniFocus perspective'. Specifies it returns a task list and distinguishes between built-in and custom perspective ids. Differentiates from sibling tools like perspective_list and review_list_due.

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

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

Provides explicit guidance on when to use this tool (to evaluate a perspective) and when not (use review_list_due for 'review', warns about 'nearby' returning empty, notes custom perspectives require OmniFocus Pro). Includes examples of usage.

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

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

With no annotations, the description fully discloses side effects: creates and immediately deletes a temporary perspective, database state unchanged. Also specifies return format { tasks: Task[] } and mentions single OmniJS execution.

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?

Single paragraph that efficiently covers purpose, mechanism, pairing, prerequisite, usage warning, return type, side effects, and example. No redundant sentences; every sentence adds value.

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

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

For a tool with 2 parameters (one required) and no output schema, the description covers all necessary context: behavior, side effects, return type, prerequisite, and usage example. Complete for an AI agent 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 coverage is 100% with detailed parameter descriptions. The description adds minimal new parameter info beyond the schema (e.g., example usage), but provides valuable context like the empty array behavior already present in schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool previews a proposed perspective rule tree without persisting it, and contrasts with perspective_evaluate for saved perspectives. The verb 'preview' and resource 'perspective rule tree' are specific and differentiated from 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?

Explicitly explains when to use: as part of propose-then-save flow with perspective_create, and warns not to use for saved perspectives. Also notes the OmniFocus Pro prerequisite and the error return if not met.

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

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

No annotations provided, so description carries full burden. It discloses no side effects, safe to call repeatedly, and describes error cases (built-in ids, missing Pro). Also outlines return shape and provides an example.

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

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

Concise single paragraph with front-loaded purpose. Every sentence adds value: purpose, use cases, restrictions, errors, return format, example. No redundancy.

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

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

For a tool with one parameter and no output schema, the description covers all necessary information: purpose, when to use, parameter sourcing, error conditions, return structure, safety profile. Complete and self-contained.

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?

Input schema already has a detailed description for perspectiveId (100% coverage). The description adds a concrete example and reinforces the context (obtain from perspective_list, built-ins invalid). This goes beyond the schema but the schema already covers the semantics well, so a 4 is appropriate.

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

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

The description clearly states it reads the full configuration of a custom OmniFocus perspective, listing specific fields (name, aggregation, rules, icon color). It distinguishes from siblings like perspective_list and perspective_evaluate by specifying that it is for introspection and cloning, and by warning against built-in perspectives.

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

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

Explicitly states when to use (introspect before evaluating, cloning) and when not (built-in perspectives, which cause validation errors). Provides alternative tool perspective_list for enumeration. Also notes OmniFocus Pro requirement.

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

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

With no annotations provided, the description fully bears the burden of behavioral disclosure. It clearly states the tool is read-only, has no side effects, and returns specific fields (id, name, kind, requiresPro), providing complete transparency.

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

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

The description is extremely concise, consisting of two sentences and an example call. It is front-loaded with the primary action and effectively conveys all necessary information with 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?

Despite having no output schema, the description explicitly lists the return fields and provides usage context. The tool is simple with no parameters, and the description fully addresses its behavior and output.

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

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

The tool has zero parameters, so per guidelines the baseline is 4. The schema coverage is 100%, and the description does not need to add parameter information since there are none.

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 lists all perspectives in OmniFocus, specifies included types (built-in and custom), and explicitly distinguishes it from perspective_evaluate, making the purpose very specific and unambiguous.

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

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

The description provides explicit guidance on when not to use this tool (for evaluation, prefer perspective_evaluate) and notes that it is safe to call repeatedly with no side effects, offering clear usage 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?

Despite no annotations, the description fully discloses behavioral traits: it explains the partial-patch behavior (only provided fields written), the side effects (writes to OmniFocus, invalidates cache, sets syncPending), the requirement for OmniFocus Pro, and special handling of null/empty values for iconColor and rules. Return value { id } is also specified.

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 fairly long but each sentence is informative and earns its place. It could be slightly more concise, but given the complexity of the tool (5 parameters, nested rule structure), the length is justified. Front-loading is good: first sentence defines operation.

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?

Considering the tool's complexity, full schema coverage, and no output schema, the description is remarkably complete. It covers all essential aspects: operation, parameter behaviors, constraints, side effects, return value, prerequisites, and examples. No gaps identified.

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 high. The description adds significant value beyond the schema by explaining the effect of null iconColor, empty rules array, the round-trip nature of rules, and the constraint that built-in perspectiveIds are rejected. This goes well beyond the schema's own descriptions.

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

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

The description clearly states 'Partial-patch update of a custom OmniFocus perspective' and enumerates exactly what can be updated (name, rules, iconColor, aggregation). It distinguishes from perspective_create and explicitly mentions that built-in perspectives are not modifiable, providing strong purpose clarity.

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

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

The description explicitly states when to use this tool (rename, retune rules, swap aggregation, recolor icon) and when not to use it (DO NOT use for create or built-in perspectives), and even provides alternatives (perspective_create). This is excellent 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?

Despite no annotations, description fully discloses side effects (may mutate data, need sync_trigger for multi-device changes), error behavior (throws NotFound), and return format ({ result }).

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

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

Well-structured with front-loaded main action, but slightly verbose; could be trimmed while retaining all key info.

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

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

Covers all aspects: purpose, usage, parameters, side effects, errors, return value, and examples. No output schema needed as return format is explained.

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

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

Schema coverage is 100%, but description adds meaning: explains identifier as bundle ID with example, and arg as optional JSON-serialisable forwarded to Action.args[0], providing context beyond schema.

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

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

Clearly states the tool invokes a named Omni Automation plug-in action in OmniFocus, with specific verb and resource. Distinguishes from sibling tool run_omnijs_script for raw JavaScript execution.

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

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

Explicitly states when to use (specific installed plug-in) and when not to use (not for built-in operations, not for arbitrary JavaScript). Points to alternative run_omnijs_script and explains parameters with examples.

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

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

With no annotations, the description fully discloses behavioral traits: projects are hidden from active views, atomic validation, best-effort per-index outcomes, side effects (writes to OmniFocus, sets meta.syncPending = true), and need for sync_trigger. It also details the return format.

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 paragraph with dense, useful information. Each sentence adds value, though it could be slightly more structured (e.g., bullet points). No redundancy.

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

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

For a batch mutation tool with atomic validation and best-effort semantics, the description covers all essential aspects: purpose, usage, side effects, return format, and synchronization requirements. No output schema but the description compensates.

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 description adds limited value beyond the schema. It provides an example and notes that the response carries the project name, but the parameter description is already clear in the schema.

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

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

The description clearly states it marks many OmniFocus projects as completed in a single JXA round trip, and explicitly distinguishes from the sibling tool project_complete by recommending this tool over repeated calls when completing more than one project.

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

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

It explicitly recommends use for completing multiple projects over repeated project_complete calls, and describes atomic validation and best-effort execution. It does not explicitly state when not to use, but the guidance 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?

With no annotations, description fully covers: atomic validation, best-effort execution, response structure, side effects (writes to OmniFocus, sets syncPending), and need to call sync_trigger. Provides comprehensive behavioral insight.

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?

Dense but well-structured: starts with main verb, explains behavior, compares to alternatives, describes validation and execution, and provides an example. Every sentence adds value; no extraneous text.

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

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

Given complexity of batch operation with atomic validation and best-effort execution, description fully explains all critical aspects: the process, response format, side effects, and sync requirements. No output schema but return structure is described.

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

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

Schema coverage is 100% and already describes the 'items' parameter. Description adds example usage and confirms each item is { id }, but does not add new semantic information beyond what schema 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?

Description clearly states 'Cancel (drop) many OmniFocus projects' with specific verb and resource. Distinguishes from project_delete and project_drop, and explains that dropped projects remain but are inactive.

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

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

Explicitly says 'Prefer this tool over repeated project_drop calls whenever dropping more than one project.' Also distinguishes from project_delete and explains atomic validation and best-effort execution, giving clear when-to-use guidance.

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

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

With no annotations, the description fully discloses side effects (sets completionDate, removes from active projects, sets syncPending) and return format, ensuring the agent understands the impact.

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

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

Very concise: three sentences plus an example, no fluff, front-loaded with purpose.

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

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

For a simple tool with one parameter, the description covers purpose, usage, side effects, return format, and includes an example. Complete without requiring an output 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% and describes the 'id' parameter sufficiently. Description adds minimal extra value but is adequate.

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

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

Clearly states the action ('marks it done with today's date and moves it out of the active view') and distinguishes from 'project_drop' which archives without completing.

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

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

Explicitly tells when to use ('when a project is finished') and when not to (archiving/hiding without completing), and suggests the alternative 'project_drop'.

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

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

No annotations provided, so description carries full burden. It states 'No side effects: read-only by contract — never mutates OmniFocus'. This fully discloses behavioral traits. No 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?

Description is concisely written in a few sentences, front-loaded with purpose, and includes essential usage info and example without any fluff.

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

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

Given low complexity (1 param, no output schema), the description fully covers what the tool does, its return value, its read-only nature, and how to use it in conjunction with project_complete.

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

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

Schema coverage is 100% with a clear description for the only parameter (id). Description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool previews what project_complete would do without changes. It uses a specific verb ('preview') and resource ('project completion'), and explicitly distinguishes from the sibling project_complete.

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

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

Explicitly says when to use (dry-run companion) and when not to (do not use to actually complete). Names alternative tool (project_complete) and provides usage pattern: pass same args, inspect plannedChanges, then call write 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 discloses side effects (creates a project, sets syncPending), idempotency behavior with key, and the need to call sync_trigger for multi-device sync. With no annotations, this provides valuable behavioral context beyond the action itself.

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 relatively concise given the 14 parameters. It front-loads the core purpose, then lists parameters efficiently. Examples are provided. However, it could be trimmed slightly by removing redundant phrases like 'Optionally place it in a folder' since the parameter list covers it.

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 14-parameter creation tool with no output schema, the description covers return format, idempotency, side effects, and follows up with sync guidance. The examples illustrate typical use cases. Minor gap: it does not clarify that the tool may fail if the folderId is invalid, but overall complete enough.

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 schema already documents all parameters. The description adds limited value by explaining idempotency_key's purpose and providing aliases for status and completionCriterion. The examples are helpful but don't substantially deepen parameter understanding beyond the schema.

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

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

The description clearly states 'Create a new OmniFocus project' with a specific verb and resource. It lists optional placement, tags, dates, etc., making the purpose unambiguous. However, it does not differentiate from sibling tools like project_create_describe, which is a dry-run variant.

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 does not mention when not to use it, nor does it compare to project_create_describe, project_batch_complete, or other creation-related tools.

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

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

Discloses no side effects, read-only by contract, never mutates OmniFocus. Describes return value structure. No annotations provided, but description adds sufficient behavioral context.

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

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

Two sentences plus an example, front-loaded with purpose, no wasted words. Efficient and 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?

With 14 parameters and no output schema, description explains return value and no-side-effect guarantee. Could elaborate on plannedChanges contents, but sufficient for typical use.

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

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

Schema coverage is 100% with parameter descriptions. Description adds minimal extra meaning beyond noting to pass same args as write tool. 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?

Clearly states it previews project creation without changes, uses specific verb 'preview' and resource 'project_create'. Distinguishes from sibling 'project_create'.

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

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

Explicitly warns against using for actual creation, directs to 'project_create' instead. Provides workflow: dry-run companion, inspect plannedChanges, then call write 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?

Discloses irreversible cascade deletion, side effects (syncPending=true), return format, and dependency on sync_trigger for cross-device updates. No annotations provided, but description fully carries the burden with rich behavioral detail.

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

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

Every sentence adds value; front-loaded with critical irreversible warning, then usage guidance, safety controls, and examples. Efficiently structured without redundancy.

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

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

Covers all aspects: what it does, when to use, safety, side effects, return value, and cross-device sync implications. No output schema exists but return format is clearly described. Adequate for a complex destructive tool.

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

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

While schema coverage is 100% and provides basic descriptions, the description adds contextual meaning: purpose of dry_run as preview, expectedModifiedAt as optimistic concurrency guard, idempotency_key for retry safety. Adds examples demonstrating usage.

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

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

Clearly states 'permanently delete an OmniFocus project and ALL its contained tasks' with specific verb+resource and irreversible nature. Distinguishes from sibling 'project_drop' by contrasting recoverable vs permanent deletion.

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

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

Explicitly tells when to use (only with explicit user intent to permanently remove) and when not to (prefer project_drop for recoverable status change). Provides safety controls and examples for dry_run, expectedModifiedAt, and idempotency_key.

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

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

No annotations provided, but description fully covers behavior: returns { description, plannedChanges }, no side effects, read-only by contract, never mutates OmniFocus. Clearly states it's a preview only.

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

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

Description is concise with front-loaded purpose. Three sentences cover purpose, usage, behavior, and return value. Minor redundancy in 'No side effects' and 'read-only by contract' but overall 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?

Given no output schema, description adequately describes return structure ({ description, plannedChanges }). Covers no side effects, read-only nature, and relationship to write tool. Does not mention idempotency or optimistic concurrency, but these are in schema and not critical for usage understanding.

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 all 4 parameters fully documented. Description adds little beyond the schema for parameters, only a brief usage hint about passing same args. Baseline 3 is appropriate as description doesn't significantly enhance parameter understanding beyond schema.

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

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

Clearly states it previews what project_delete would do without changes, using specific verb 'Preview' and resource 'what project_delete would do'. Distinguishes from sibling tool project_delete by explicitly saying 'Do NOT use to actually delete a project — use project_delete instead'.

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

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

Explicitly tells when to use (dry-run companion) and when not to use (don't want to delete). Provides alternative: 'use project_delete instead'. Gives example workflow: pass same args, inspect plannedChanges, then call write tool.

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

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

No annotations provided, so description carries full burden. It discloses side effects: changes project status, sets meta.syncPending = true, and describes return value shape, giving the agent full behavioral understanding.

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 clear sentences plus an example. Every sentence adds value, no redundancy. Front-loaded with action and side effects.

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

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

Complete for a simple tool: describes action, usage guidance, side effects, return value, and provides an example. No gaps given one parameter and no output 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?

Only one parameter (id) with schema description coverage 100%. Description adds example usage but no additional semantic detail beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the action: marks a project as on-hold/dropped, removes from active view without completing. It distinguishes from project_complete, showing clear purpose.

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

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

Explicitly says when not to use (if actually done, prefer project_complete) and provides context for deferring or abandoning. This helps the agent select the right tool.

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

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

With no annotations provided, the description fully carries the burden of explaining behavior. It states 'No side effects: read-only by contract — never mutates OmniFocus.' and describes the return value { description, plannedChanges }. This provides good transparency, though details on error handling or edge cases are missing.

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

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

The description is concise, with 4 sentences that are front-loaded with the primary purpose. Every sentence adds value: purpose, usage warning, return object, read-only guarantee, and example usage pattern. No unnecessary words.

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

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

Given the tool has only one parameter and no output schema or annotations, the description covers the essential elements: purpose, usage instructions, return type, and safety guarantee. It could mention error behavior or input validation, but overall it is adequately complete for typical use.

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

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

The schema already describes the 'id' parameter with a pattern and description, providing 100% coverage. The description adds context by referencing 'the same args you would to the write tool', but does not add further detail beyond the schema. 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 tool's purpose as a dry-run for project_drop: 'Preview what project_drop would do without making any changes.' It distinguishes from the sibling project_drop by using 'Preview' and 'Do NOT use to actually drop a project — use project_drop instead.'

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

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

The description explicitly states when to use this tool (to preview) and when not to (use project_drop for actual drop). It also provides a usage pattern: 'pass the same args you would to the write tool, inspect plannedChanges, then call the write tool once approved.'

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