omnifocus-mcp

by torsday

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.0.2
Disambiguation5/5
Each tool has a clearly distinct purpose, with detailed descriptions that explicitly state when to use which. Overlapping concerns are minimized through precise naming and usage guidance, e.g., task_find_by_name vs task_search vs search_query each target different search modes.
Naming Consistency5/5
Tool names follow a consistent verb_noun pattern (e.g., task_create, folder_list) with a cohesive sub-naming for batch operations (task_batch_*) and describe variants. Minor exceptions like 'clarify' are single-purpose helpers that do not break the overall pattern.
Tool Count1/5
With 146 tools, the server far exceeds the recommended range. Even considering the complexity of OmniFocus, the count is extreme and likely overwhelms agents, with many redundant describe variants and separate tools that could be merged.
Completeness5/5
The server covers the full lifecycle of tasks, projects, folders, tags, perspectives, attachments, notes, reviews, sync, webhooks, and UI control. It includes batch operations, search, forecasting, templates, and advanced features like decisions and waiting-on, leaving no obvious gaps.
Average 4.7/5 across 146 of 146 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- 8 of 9 community issues answered or closed in the last 6 months
- 147 commits in the last 12 weeks
- Last stable release on June 11, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose4/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains atomic validation, best-effort execution with per-index outcomes, side effects (writes to OmniFocus, sets syncPending), and return format. Lacks mention of authentication or rate limits, but sufficient for most use cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and front-loaded with purpose. Every sentence adds value: purpose, use case, behavior, return format, side effects, example. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description fully documents return values with structure and purpose (task name for agent usage). Covers validation, execution model, side effects, and sync dependency. Complete for agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds minimal extra meaning beyond schema (example, mentions { id } each item), but does not elaborate on idempotency_key usage or pattern beyond schema. Adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly defines verb ('Mark many OmniFocus tasks as incomplete'), resource ('OmniFocus tasks'), and scope ('batch'). Distinguishes from sibling tools like task_batch_complete and task_uncomplete by emphasizing batch nature and reversal of completion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit preference over repeated task_uncomplete for batches, and explains atomic validation and best-effort execution. Could be more explicit about when to use task_uncomplete for single tasks, but context is clear from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It explicitly states 'No side effects: read-only by contract — never mutates OmniFocus' and describes the return shape. This is strong transparency for a preview tool, though it could mention error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, usage warning, and return value with workflow. Each sentence earns its place, no fluff. Slightly verbose but well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the dry-run workflow, return shape ({description, plannedChanges}), and how to use it with the write tool. Given no output schema, this is sufficient for an agent to use the tool correctly. Could mention error cases, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each field. The description adds only that parameters should match those of task_batch_update and that items is an array of {id, patch} pairs. This is helpful but not significantly beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Preview what task_batch_update would do without making any changes.' It identifies the tool as a dry-run for task_batch_update and distinguishes it from sibling task_batch_update by explicitly warning against using it for actual updates. The verb 'preview' and resource 'task_batch_update' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (preview), when not to use (do not actually update tasks), and provides a full workflow: 'pass the same args you would to the write tool, inspect plannedChanges, then call the write tool once approved.' This is clear and actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses idempotency, return shapes, side effects (writes tag+note, sets syncPending). Missing error cases, but given no annotations, this is thorough for a simple mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded, and each sentence adds value (core action, idempotency, alternatives, returns, side effects, example). No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, returns, side effects, and idempotency. No output schema, but return shapes are described. Lacks error handling details, but sufficient for single-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter description; the description adds an example but no additional semantic value beyond what schema provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool clears waiting-on tracking from an OmniFocus task, specifying it strips a fenced block and removes a tag. This distinguishes it from siblings like task_delete 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (to clear waiting-on) and when not to (to delete task or remove unrelated tags), with named alternatives (task_delete, task_update).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states 'No side effects: read-only by contract — never mutates OmniFocus,' which is a key behavioral trait. It also mentions the return envelope format. However, it does not detail error conditions (e.g., invalid id) or behavior when dry_run parameter is not set (the parameter exists in schema but not mentioned in description). Still, the main behavioral aspect is well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with four sentences covering purpose, warning, output, and usage. It is clear and efficient, but could be slightly more structured (e.g., bullet points for key points). No unnecessary words, but not maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a dry-run preview with no output schema, the description explains the return value (plannedChanges) and the read-only nature. It also gives a usage example. However, it omits mention of the dry_run parameter (exists in schema) and does not cover what happens if the update would fail validation, which would be useful for a preview tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add per-parameter detail beyond the schema; it does add overall context (same args as task_update, returns plannedChanges). But since schema already has thorough descriptions, the description does not significantly improve parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it previews task_update without making changes, explicitly distinguishes from task_update, and specifies the output (description, plannedChanges). The verb 'preview' and resource are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use (before task_update), when not to use (not for actual updates), and provides a usage pattern: pass same args, inspect plannedChanges, then call write tool. It names the alternative (task_update) and explains the companion relationship.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds important behavioral context: 'Returns projects[] with pagination; safe to call repeatedly; no side effects.' This goes beyond the schema. However, it does not mention rate limits or authentication, which are typical concerns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (three sentences plus two inline examples) and front-loaded with the purpose. Every sentence adds value, with no fluff. The examples are concise and illustrative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 10 parameters and no output schema, the description covers core functionality, safety, and pagination. It could be improved by noting that the cursor must respect filter consistency (already in schema but useful in description). Overall, it provides sufficient context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 lists some filters (folderId, status, flagged, reviewDueBefore) but does not add significant meaning beyond the schema's own detailed descriptions. The examples are helpful but not enough to raise the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (List) and resource (projects), and explicitly distinguishes this tool from the sibling 'project_get' by specifying when not to use it. 'List projects in OmniFocus with optional filters' is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use ('Use for queries across projects') and when not to ('Do NOT use for a known single project'), naming the alternative (project_get). Also mentions filters and provides examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses side effects ('changes the project's folder, sets meta.syncPending = true') and return value details (includes name for agent to describe change). Lacks error conditions or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with multiple sentences, each adding value. It includes examples and front-loads the core purpose. No redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema, the description covers purpose, parameters, side effects, and return value. It lacks error handling or permissions, but is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds context about null folderId moving to root, but this is also in the schema. Examples demonstrate usage but don't add semantic meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Move an OmniFocus project to a different folder' with a specific verb and resource. It distinguishes from siblings like project_complete and project_drop by explicitly saying 'Do not use to complete or drop a project.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('Use when reorganizing projects') and when not to use ('Do not use to complete or drop a project'). Examples show correct invocation with folderId or null.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return structure, side effects (writes folder+project, sets syncPending), and metadata format. Lacks explicit statement that original project is unmodified, but overall good coverage given no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences front-loaded with main action, followed by structure, guidance, return/side effects, and example. No fluff, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return value, side effects, folder location via env var, and example. Does not address templateName uniqueness enforcement or ID format, but given low complexity, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description repeats schema descriptions for parameters but adds contextual example showing usage of templateName and parameterNames. No new semantic insight beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool captures a project as a reusable template, naming the folder location. It distinguishes from sibling task_duplicate, making 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs not to use for one-off duplication and directs to task_duplicate, providing clear when-to-use and when-not-to-use guidance. Implies appropriate context for template creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It discloses the tool modifies state, is Pro-only, triggers sync, and provides an example. However, it does not explicitly state whether it overwrites an existing location trigger or how to remove one, which is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one paragraph of 5 sentences plus an example. It is front-loaded with the core purpose, concise, and contains no fluff. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, 5 required, no output schema, and no annotations, the description covers purpose, alternatives, side effects, error condition, and includes an example. It does not mention how to clear a location trigger, but overall it is fairly complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, baseline is 3. The description restates schema info for each parameter (id, name, trigger, latitude, longitude, radiusMeters) without adding significant new meaning. The example call adds clarity but does not compensate beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set a geographic location trigger on a tag' with specific verb and resource. It distinguishes from sibling tag_get_location by explicitly saying 'Do not use to read the current location; prefer tag_get_location instead'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use (to set a trigger), when-not-to-use (to read location), alternatives (tag_get_location), prerequisites (get tag ID from tag_list), and side effects (triggers sync, should call sync_trigger). It also warns about OmniFocus Pro requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description discloses behavioral traits: it overwrites existing rules, returns only the updated task ID (not full object), and mutations don't sync automatically. This is helpful, though it could include more on error handling or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two core sentences and two examples, all front-loaded and waste-free. Every sentence serves a purpose: stating action, overriding behavior, alternatives, return value, sync caveat, and illustrative examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested input and no output schema, the description covers key aspects: what it does, return format, sync behavior, and examples. It doesn't need to repeat schema details. A small gap is lack of mention of error scenarios or validation, but overall it's complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions. The description adds value through two examples showing valid rule structures, which helps clarify the nested object even though the schema already explains it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set the repetition rule') and the resource ('OmniFocus task'). It distinguishes from the sibling tool 'task_clear_repetition' by mentioning its purpose for removal, and provides concrete examples showing usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description guides usage by noting when to use the alternative (task_clear_repetition to remove) and warns about sync behavior (call sync_trigger for cross-device visibility). However, it doesn't explicitly mention prerequisites (e.g., task must exist) or compare with other similar tools like task_set_alarms.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses no side effects, safe to call repeatedly, and describes return shape. Omits error handling for missing IDs, but still strong for a get tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with examples. No redundant information; every sentence serves a purpose. Front-loaded with purpose and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of a get tool with 5 well-described parameters, the description covers return shape, default behavior, and safety. Examples cover main use cases. Complete for the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with detailed descriptions. Description adds examples for id and includeTaskTree and states default for includeTaskTree, but does not significantly expand on schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Fetch a single OmniFocus project by persistent ID' with a specific verb and resource. It distinguishes from sibling tool project_list by explicitly advising against cross-project queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Do NOT use for queries across projects — use project_list.' Provides clear when-to-use and when-not-to-use guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses return behavior (success object and TemplateNotFoundError), side effects (removes template, sets syncPending), and error distinction. It lacks details about undo or permanent deletion, but overall is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences front-loaded with purpose, followed by return, error, side effect, usage warning, and example. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 and no output schema, the description covers return value, error handling, side effects, and usage boundary. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the parameter well (case-insensitive match, minLength). The description adds an example but no new semantic value beyond reinforcing the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), resource (saved project template), and location (Templates folder). It distinguishes from the sibling tool project_delete with an explicit warning, ensuring the agent selects the correct tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not-to-use guidance ('Do NOT use to delete ordinary projects — call project_delete') and includes an example, making it easy for the agent to decide when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description explicitly states the tool has no side effects, is safe to call repeatedly, and returns a sorted list. It also describes the sorting order and return fields, adding behavioral context beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with four sentences that front-load the core purpose. Every sentence adds value: purpose, eligibility, sorting, distinction from sibling, return fields, and safety. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no output schema), the description fully covers what the tool does, what it returns, and when to use it. It includes eligibility, sorting, and return fields, making it complete for an effective tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is trivially 100%. The description adds no parameter-level detail but compensates by explaining the implicit filtering criteria (date conditions and project status). Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists projects due for review, specifying the resource (projects), action (list due), and condition (next review date today or earlier or never set). It also distinguishes itself from the sibling tool project_list by advising not to use it to get all projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use (for due review projects) and explicitly advises against using it to get all projects, pointing to project_list as the alternative. However, it does not include further exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Returns tag details; no side effects' and includes 'including task count.' This adequately discloses behavior for a simple read operation, though it lacks details on authorization or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a brief example. Every part is essential: purpose, usage constraint, behavior, example. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with no output schema, the description covers purpose, usage guidance, side effects, and provides an example. It is fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters fully documented in the schema. The description adds only an example call, not significantly enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a single tag by its persistent ID, including task count.' The verb 'fetch' and resource 'tag by ID' are specific, and it distinguishes itself from tag_list by warning not to use it for listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Do not use to list multiple tags; prefer tag_list instead,' providing a clear alternative and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares read-only nature: 'No side effects: read-only by contract — never mutates OmniFocus.' No annotations provided, so description carries burden. Could mention error behavior (e.g., invalid id), but key behavioral trait is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, each serving a distinct purpose: purpose, warning, return, safety, example. No superfluous text, well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 (description, plannedChanges). Covers purpose, usage, safety, and example. Completely adequate for a dry-run tool with full schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description does not add new parameter information beyond what schema provides; it only references 'same args' generically.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Preview what tag_update would do without making any changes.' Clearly distinguishes from tag_update by warning not to use for actual updates. Indicates return structure (description, plannedChanges).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (preview) and when-not-to-use (actual update) with alternative named (tag_update). Includes a usage example: 'pass the same args... 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses that the tool returns ALL matching tasks (non-unique names), is safe to call repeatedly, has no side effects, and returns an empty array for zero matches. This fully compensates for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but slightly verbose. It front-loads the main purpose and includes examples, but could be tightened slightly. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description explains return type (tasks[]) and empty array behavior. It covers side effects and safety. Missing details on pagination or rate limits, but acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 two examples and explains the matchMode options (though uses 'matchMode' instead of schema's 'mode', causing minor inconsistency). It does not describe other parameters (limit, caseSensitive) beyond schema, so it adds limited value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds tasks by name in OmniFocus, distinguishing it from siblings like task_get (by ID) and search_query (full-text search). The verb 'find' combined with the resource 'tasks by name' is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs alternatives: prefer task_get with an ID, and use search_query for full-text content. Also clarifies behavior (empty array on no matches, no side effects), which helps the agent decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses side effects (clears completedAt, sets syncPending), return value structure with noChange flag, and idempotency. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus an example. Front-loaded with action, then details and side effects. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return values and their semantics (done, noChange, name allows agent to describe change). Side effects are fully specified. Complete for a simple mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter fully described in schema (id with pattern and description). Description adds no extra meaning, but schema coverage is 100%, meeting baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'Mark an OmniFocus task as incomplete' with clear verb and resource. Distinguishes from siblings like task_complete and task_delete by noting it is the inverse of completion and not for deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly warns against using for drop/delete. Mentions idempotency. Lacks explicit comparison to batch variants like task_batch_uncomplete, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses side effects (clears droppedAt, sets meta.syncPending), return format (two possible objects), and idempotency. This is comprehensive for a single-operation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with purpose, and efficiently covers return types, side effects, and an example. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 explains return values, behavior, and side effects. It is complete for a simple restoration tool with one parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 'id' parameter. The description adds an example call but does not enrich the parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Restore a dropped OmniFocus task — clears its dropped status and returns it to the active view,' which uses a specific verb ('restore') and resource ('dropped task'), and uniquely identifies the tool among many task-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear negative guidance ('Do not use to complete a task') and explains idempotent behavior, but does not explicitly compare to sibling tools like task_uncomplete or task_batch_undrop. However, the intent is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: the environment gating, URL rejection, secret handling (never echoed, stored on disk only), return value omission, side effects (writes to config file with mode 0600), and the outbound-only nature. This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with the core purpose, followed by constraints, behavioral details, side effects, and an example. Every sentence adds value, and it is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 4 parameters and nested trigger objects, the description covers all essential aspects: purpose, prerequisites, behavioral details, side effects, return value, and an example. It is complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds limited new meaning beyond the schema. It provides an example and contextual warnings (e.g., 'Do NOT use this to call this MCP server itself'), but the parameter descriptions are already detailed in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Register an outbound webhook that fires when an OmniFocus state change matches the supplied trigger.' It uses specific verbs and resources, and distinguishes from sibling tools like webhook_delete, webhook_list, and webhook_test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool, including the environment variable requirement and the HTTPS-only URL constraint. It warns against using it to call the MCP server itself. However, it does not explicitly compare to other webhook tools or specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'No model calls; no side effects' and explains the three return shapes (ok, ambiguous, error) and their implications. It also notes that time-of-day and end-conditions are only in normalizedDescription. However, it does not mention potential input length limits or exact format constraints, so it is slightly less than perfectly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then covers return shapes, supported patterns, usage guidelines, and examples. It is thorough but not overly verbose; every sentence adds value. It could be slightly more concise, but the structure is logical and easy to follow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description fully explains the three possible return shapes and their contents. It covers supported patterns, error cases, and provides usage context (with task_set_repetition or task_create). It also clarifies the anchor parameter's informational nature. The description is complete and leaves no major gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters having descriptions. The tool description adds significant value beyond the schema by providing examples for the prose parameter (e.g., 'every Monday', 'first Thursday of every month') and explaining the role of the anchor parameter as 'currently informational' and that embedding time-of-day is the agent's responsibility. This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'Deterministic prose-to-RepetitionRule helper' and explains its function of converting natural-language phrases to structured rules. It distinguishes itself from sibling tools like task_set_repetition by explicitly stating when not to use it: 'Do NOT use this tool when the agent already has a structured RepetitionRule from another source.' This meets the highest standard of purpose clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: 'Prefer this helper over ad-hoc LLM translation whenever the user's repetition phrasing is the only signal.' It also specifies when to use an alternative: 'call task_set_repetition directly' if a structured rule already exists. This gives clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully discloses behavior: 'No side effects: read-only by contract — never mutates OmniFocus.' Also describes return value structure { description, plannedChanges }.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with 5 sentences; each adds value. Could be slightly tighter, but well-structured and front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description explains return value shape. Covers dry-run pattern, safety, and usage flow comprehensively for a 2-param preview tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters. Description adds context about passing same args as write tool, but doesn't elaborate beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Preview what tag_move would do without making any changes.' Distinguishes from sibling tool tag_move by specifying not to use for actual moves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Do NOT use to actually move a tag — use tag_move instead.' Provides example usage: pass same args as write tool, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It details atomic validation, best-effort execution, per-index outcomes, side effects (creates tasks, sets meta.syncPending = true), and idempotency key behavior. Agent gains a clear understanding of what happens during and after invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with key points front-loaded: purpose, key behaviors, usage advice, parameter summary, return format, side effects. It is slightly lengthy but every sentence contributes value. Could be trimmed by a couple of words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (batch creation with validation, best-effort, idempotency, side effects), the description covers all essential aspects: what it does, when to use, behavioral details, return format, and side effects. No output schema exists, so the return format description is crucial and well-provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions on all parameters. The description adds context beyond the schema by explaining batch behavior (atomic validation, best-effort), idempotency_key purpose, and the return shape. However, it does not elaborate on individual parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create many OmniFocus tasks in a single JXA round trip.' It distinguishes itself from sibling tools by specifically recommending this tool over repeated task_create calls for multiple tasks. The verb 'create' and resource 'tasks' are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises when to use this tool: 'Prefer this tool over repeated task_create calls whenever you are creating more than one task.' It also covers idempotency key usage for retries. It does not explicitly state when not to use (e.g., for a single task), but that is implied by the sibling tool task_create being preferred for single tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses atomic validation, best-effort execution, side effects (writes, syncPending), need for sync_trigger, and return format. Fully transparent about mutation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with core purpose; each sentence adds value. Could be slightly more concise (e.g., combine some sentences), but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 well-documented parameters, no output schema (but description explains return format), and batch complexity, the description covers behavior, side effects, alternatives, and examples completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds meaning beyond schema: explains OmniJS context, mutual exclusivity of projectId/parentId, and behavior when both omitted (inbox). Includes an example, adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb+resource ('Move many OmniFocus tasks') and distinguishes from sibling 'task_move' by noting it's a batch operation and mentions the underlying technology (OmniJS vs JXA), clearly differentiating from repeated single-task calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to prefer this tool ('over repeated task_move calls whenever moving more than one task'). Provides constraints on destination fields and validation behavior, but does not explicitly list when NOT to use it (e.g., if only one task).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses critical behavior: 'No side effects: read-only by contract — never mutates OmniFocus.' It also states the return format '{ description, plannedChanges }' and confirms no mutations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences plus an example), front-loaded with the core purpose, and each sentence adds value. Slightly verbose example could be trimmed, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 type and the dry-run pattern. All parameters are documented in schema, and the context of usage with the sibling tool is clear. Complete for a preview tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 mentions passing 'the same args you would to the write tool' but adds no specific parameter semantics beyond what the schema already provides. The schema fully describes 'at' and 'id'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 task_complete would do without making any changes.' It explicitly distinguishes from the sibling 'task_complete' and uses a specific verb+resource ('preview completion').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Do NOT use to actually complete a task — use task_complete instead.' Also explains the dry-run pattern and advises to inspect plannedChanges before calling the write tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: marks as dropped/deferred, removes from active view, idempotent (noChange flag), reversible, side effects (sets droppedAt and syncPending), and return format. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear front-loaded purpose, key facts (reversible, idempotent), an example, and no fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is thorough, covering return values (done or noChange with id and name), side effects, and an example. It does not describe error scenarios or prerequisites (e.g., task must exist), but given the tool's simplicity and the lack of output schema, it is highly complete for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters (id, at). The description adds minimal value by mentioning the optional ISO-8601 date and the default behavior, but these are already present in the schema. A score of 3 is appropriate as the description does not significantly enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool drops an OmniFocus task, marks it as dropped/deferred, and removes it from active view. It explicitly distinguishes from siblings like task_undrop, task_complete, and task_delete, guiding the agent to use the correct tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use (dropping/deferring a task), when not to use (completing or deleting), and mentions an alternative (task_undrop for reversal). It also explains idempotency and return values, aiding correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'No side effects: read-only by contract — never mutates OmniFocus.' This is critical behavioral information for a tool that could be mistaken for a write operation. Since no annotations are provided, the description fully shoulders the burden of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with only three sentences, each serving a clear purpose: stating the action, providing a negative directive, and detailing behavior and return value. No extraneous information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, no annotations), the description adequately covers purpose, usage, and side effects. It lacks explicit error handling details but is sufficient for correct invocation alongside its sibling tool task_drop.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for both parameters (id and at) in the schema. The description adds context that the same args should be passed as to the write tool, but does not significantly enhance parameter understanding beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Preview what task_drop would do without making any changes.' It clearly distinguishes itself from the sibling tool task_drop by instructing not to use it for actual drops. The return value is described, leaving no ambiguity about the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Do NOT use to actually drop a task — use task_drop instead.' It also outlines a workflow: pass the same arguments, inspect plannedChanges, then call the write tool. This clearly differentiates usage from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: read-only, missing IDs omitted, return order, example, and meta.warnings. It also details parameter behaviors beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4-5 sentences), front-loaded with purpose, includes an example, and every sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, no output schema), the description covers purpose, usage, behavioral details, and parameter behavior adequately. It explains return values and warnings, though meta structure could be more detailed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 some context (e.g., 'missing IDs omitted') but largely echoes schema. No significant new meaning beyond what's in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch up to 100 tasks by persistent ID' with a specific verb and resource, and distinguishes itself from siblings like task_get and task_find_by_name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use (multiple IDs from multiple sources) and when not to use (single ID -> task_get, names only -> task_find_by_name), along with read-only and safe-to-retry guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states 'Returns tasks[] with pagination; safe to call repeatedly; no side effects,' which discloses key behavioral traits. However, it could be more explicit about read-only nature or potential performance impacts, but overall it is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at about 5 sentences, well-structured with purpose, usage guidelines, and examples. Every sentence is informative and none are redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (20 parameters, no output schema), the description covers purpose, usage, behavioral traits, and examples. It mentions pagination but lacks detail on return format; however, the schema and parameter descriptions fill that gap. Overall complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 through usage examples (e.g., task_list({ inbox: true })) and clarifies that filters like `inbox` cannot be combined with `projectId`. This goes beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List tasks in OmniFocus with optional filters' and distinguishes from siblings like task_get, task_find_by_name, and search_query. It specifies the verb 'list' and resource 'tasks' with scope, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly states when to use this tool ('filter-based queries across tasks') and when not to, with direct alternatives for single task retrieval, name lookup, and full-text search. This provides clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses idempotency (returns noChange:true for unknown names), side effects (rewrites config file), and configuration requirement (off by default).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences with front-loaded purpose. Includes a valuable example but is slightly lengthy. Generally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers return values, side effects, and configuration. For a simple delete tool with one parameter, it provides all necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents the name parameter's idempotency and return behavior. The description does not add additional parameter meaning beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a registered outbound webhook by name, distinguishing it from sibling tools like webhook_list, webhook_register, and webhook_test. It specifies it removes exactly one entry and is idempotent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (delete a specific webhook by name) and when not to use (not for bulk-clear operations). Also notes the requirement for environment variable OMNIFOCUS_WEBHOOKS_ENABLED=1.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly states 'No side effects: read-only by contract — never mutates OmniFocus.' This fully discloses the read-only nature. It also describes the return value structure. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of 4 sentences, each earning its place. It is front-loaded with the core purpose (Preview), then usage guidance, then behavior, then example workflow. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple dry-run nature, the description completely covers purpose, usage, behavior, constraints, and return value. No output schema exists, but it describes the return shape ({ description, plannedChanges }). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters (id, folderId). The description adds 'pass the same args you would to the write tool' as context but does not provide additional semantics beyond what the schema offers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Preview') and resource ('what project_move would do'). It explicitly distinguishes from the sibling tool 'project_move' by noting 'Do NOT use to actually move a project — use project_move instead.' The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('Preview what project_move would do') and when-not-to-use ('Do NOT use to actually move a project'). It includes a typical workflow: pass same args, inspect plannedChanges, then call the write tool. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses side effects (writes new project, sets syncPending) and return value structure, going beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive: front-loaded purpose, includes restrictions, behavior, return, and example. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main purpose, side effects, return values, and parameter behavior. Lacks details on error cases or if no dueDate, but overall sufficient for a tool with 4 params and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: explains placeholder substitution, date shifting, and provides an 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Spawn a new project from a saved template' and distinguishes from sibling 'task_duplicate' by explicitly stating when not to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not-to-use guidance: 'Do NOT use to copy a one-off project — prefer task_duplicate.' Implies appropriate use for template-based instantiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'No side effects: read-only by contract — never mutates OmniFocus.' It also describes the return shape ({ description, plannedChanges }) and that it is a dry-run companion. With no annotations provided, this fully discloses the behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, no wasted words. The main purpose is front-loaded in the first sentence, and subsequent sentences add necessary context without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a preview tool with no output schema, the description describes the return shape explicitly. It also mentions the dry-run concept and the relationship to project_update, providing all needed 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all 17 parameters. The description does not add per-parameter meaning beyond saying to pass the same args as project_update. Baseline is 3, and no additional value is added for individual parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it previews what project_update would do without changes, distinguishing it from the actual update tool. It specifies the verb 'preview' and the resource 'project update', and contrasts with the sibling tool project_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Do NOT use to actually update a project — use project_update instead.' It also provides a usage pattern: pass args to inspect plannedChanges then call the write tool, giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effects (writes to OmniFocus, sets syncPending=true) and return value structure (id, name, reviewIntervalDays) with behavior notes (post-mutation lookup, null if deleted). Since no annotations exist, the description fully carries this burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise; 4-5 sentences with clear front-loading of purpose, then guidelines, return info, side effects, and examples. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely covers the tool's operation for a simple mutation with 2 params and no output schema. The return value explanation compensates for missing output schema, and side effects are disclosed. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description does not add significant meaning beyond the schema; it restates that days sets the interval and null removes it. No additional param-level details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'set' and resource 'project's review interval'. It explicitly distinguishes from the sibling tool 'review_mark_reviewed' by stating not to use it for marking a project as reviewed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance. It mentions using null to remove schedule and directs to prefer review_mark_reviewed for marking reviewed. Includes examples for both cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It reveals asynchronous behavior ('starts immediately but completes asynchronously'), side effects ('triggers a sync request'), and return value ('Returns meta.syncPending = false'). Lacks details on error handling or concurrency if sync already pending, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, front-loaded with purpose, followed by usage guidelines and behavioral details. No redundant words. Every sentence adds value. Example call included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description covers all necessary context: purpose, when to use/avoid, behavior (async, side effects), return value, and example. Differentiates from sync_status sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description adds no parametric detail, but none is needed. It focuses on behavior and usage, which is appropriate given zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Kick off an OmniFocus sync') and resource ('Omni Sync Server'). It distinguishes from sibling tool sync_status by focusing on initiating sync, not checking status. The verb 'kick off' is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('after any sequence of mutations when you need changes on other devices') and when not to use ('Do not call when no mutations have been made; prefer checking meta.syncPending first'). Provides clear alternatives and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: it explicitly states 'no side effects: read-only by contract — never mutates OmniFocus' and describes the return shape as '{ description, plannedChanges }'. This is thorough transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with only three sentences, front-loading the core purpose. Every sentence adds value, and there is no redundancy or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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, no nested objects), the description is fully complete. It covers purpose, usage, behavior, and return value, leaving no ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minor context by noting 'pass the same args you would to the write tool', but this doesn't significantly enhance parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 preview for tag creation, using specific verbs like 'preview' and 'describe'. It explicitly distinguishes from 'tag_create' by stating 'Do NOT use to actually create a tag' and directing users to the sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use and when-not-to-use guidance: use to preview planned changes, do not use to actually create. It also suggests a workflow: pass same args, inspect plannedChanges, then call the write tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the transparency burden. It discloses irreversibility, deletion of children, removal from tasks, side effects (writes to OmniFocus, sets meta.syncPending), and return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (4 sentences) with key information front-loaded (irreversibility, action). Every sentence adds value without redundancy, including an example call.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the return value (deleted tag ID) and side effects. It is comprehensive for a destructive tool given the context signals and sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'id,' and the description merely echoes the schema's note to get the ID from tag_list. No additional semantic meaning is added beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Hard-delete a tag from OmniFocus' with the verb 'hard-delete' and specifies the resource (tag). It distinguishes from the sibling tool 'tag_set_status' by noting its irreversibility and recommending the alternative for preserving history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Prefer tag_set_status with status='dropped' to preserve history' and instructs users to 'Get the tag ID from tag_list,' offering clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses read-only nature, no side effects, never mutates OmniFocus. Contradictions: none.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no unnecessary words. Front-loaded with key purpose, then usage guidance, then return format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with 1 parameter, no output schema. Description explains return object structure and safety guarantees, sufficient for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100%, description mentions passing same args as tag_delete but does not add new details beyond schema's own description of id parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it previews tag deletion, distinguishes from sibling tool tag_delete via explicit warning. Uses specific verb 'preview' and resource 'tag_delete'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs not to use for actual deletion, directs to tag_delete instead. Provides 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description covers safety ('no side effects','safe to call repeatedly') and return structure (flat array, truncation with maxOutputBytes). Lacks explicit read-only label but is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise at 5 sentences, well-structured with primary purpose first, then guidelines, then examples. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, description explains return format (flat array) and key behaviors (truncation, hierarchy walking). Covers complexity of 5 parameters effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, description adds value beyond schema: explains verbose vs fields, gives examples, details maxOutputBytes truncation mechanism. Above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List all tags in OmniFocus' with filtering options, distinguishing from siblings like tag_get (single tag) and search tools. Verb and resource are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says do not use for single tag; prefer tag_get. Gives guidance on walking hierarchy with parentId and includes examples. Clear when-to-use and when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the effect of the boolean, mentions return of updated tag with confirmation, and triggers a sync. Could mention error conditions or permissions, but overall sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences plus an example. Front-loaded with purpose. No fluff, each sentence adds necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description mentions return value. It covers the operation flow (get ID, call tool, sync trigger). Complete context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with clear descriptions, but description adds context for id (from tag_list) and explains the boolean purpose. Good additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it enables or disables next-action selection for a tag, which is a specific and unique operation. It distinguishes from sibling tool 'tag_update' by explicitly saying not to use this for other properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use (next-action selection), when not to use (other properties, prefer tag_update), prerequisite (get tag ID from tag_list), and follow-up action (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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: dropped tags are hidden not deleted, returns updated tag, triggers sync, and accepts synonym values for status. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive: purpose stated first, followed by important notes, examples, and related tool references. Every sentence serves a purpose, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 value and sync behavior. Covers prerequisites (ID from tag_list), alternatives (tag_delete), and post-action steps, making it fully self-contained for a focused tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers both parameters with descriptions. The description adds synonym mapping for status and usage examples, but overall value beyond schema is moderate. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it sets lifecycle status of a tag to active, on-hold, or dropped. Distinguishes from tag_delete by noting dropped tags are hidden, not deleted, and explicitly recommends using tag_delete for permanent removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not-to-use (prefer tag_delete), directs to get ID from tag_list, includes examples, and mentions post-action sync trigger with recommendation to call sync_trigger, offering thorough guidance on usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that only supplied fields are changed (partial patch), that it returns the updated tag on success, and that it triggers a sync, advising to call 'sync_trigger' afterward. These are important behavioral traits. However, it does not explicitly mention any authorization requirements, rate limits, or potential side effects beyond the sync. Still, the information is sufficient for safe and correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (7 sentences) and well front-loaded. The first sentence states the purpose, the second clarifies the patch behavior, and the third immediately distinguishes from sibling tools. Examples are placed at the end, which is appropriate. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (1 required), no output schema, and moderate complexity, the description is complete. It covers the update behavior, the return value, the sync side effect, and prerequisites (get ID from tag_list). No important behavioral aspect is missing. The examples cover two common use cases (name change and status change).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all 5 parameters (100% coverage), providing baseline of 3. The description adds extra semantic value for several parameters: for 'id', it says 'Get from tag_list'; for 'status', it lists alias mappings (paused → on-hold, etc.); for 'parentId', it explains that passing null promotes to root and to get valid IDs from tag_list. These additions help the agent understand the domain-specific meanings beyond schema constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Update mutable fields on an existing tag (partial patch).' It specifies the resource (tag) and the verb (update). It distinguishes itself from sibling tool 'tag_move' by explicitly stating not to use it for moving a tag to a different parent, and instead recommends 'tag_move'. This provides clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Update mutable fields on an existing tag.' It also gives clear when-not-to-use guidance: 'Do not use to move a tag to a different parent; prefer tag_move instead.' Additionally, it mentions the alternative tool by name and instructs the user to get the tag ID from 'tag_list' and to call 'sync_trigger' after the update. Examples further illustrate proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explicitly declares no side effects, read-only by contract, never mutates OmniFocus. Also describes return value shape { description, plannedChanges }.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an example; front-loaded with purpose and guidance. Every sentence earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple dry-run tool with 2 params and no output schema, the description covers all needed: return value, safety, workflow, and idempotency key in schema. Completely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions; description does not add extra parameter info. Baseline 3 is appropriate as description focuses on tool purpose rather than parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it previews what task_batch_create would do without changes, using specific verb 'preview' and resource 'task batch creation'. It distinguishes from sibling by warning not to create tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when NOT to use (actual creation) and provides alternative (task_batch_create). Gives clear 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: validation is atomic (rejects whole batch on any schema failure), execution is best-effort (per-index outcomes), side effects (writes to OmniFocus, sets syncPending), idempotency key behavior, and return format with per-index results including task names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose. Every sentence adds value, covering purpose, behavior, alternatives, response format, side effects, and an example. There is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description comprehensively explains the return format, side effects, and idempotency. The batch mutation tool has 2 parameters and is fully documented. The description leaves no gaps for an agent to understand its usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema, such as explaining the batch behavior, per-index outcome reporting, and idempotency key usage. It enhances understanding of how the parameters operate in practice.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'restore' and resource 'many cancelled OmniFocus tasks' and distinguishes from sibling tools like task_batch_drop and task_undrop. It explicitly says 'Use task_batch_drop to cancel tasks' and 'Prefer this tool over repeated task_undrop calls whenever undropping more than one task.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool (for multiple undrops) and mentions the alternative (task_undrop). It also describes validation atomicity and best-effort execution, which helps the agent understand behavior. However, it does not explicitly state when not to use this tool or list other alternatives beyond undrop.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses key behaviors: it removes all alarms, returns the updated task, and notes the lack of automatic sync. This is sufficient for inferring safety and side effects. A minor gap is not specifying behavior when no alarms exist, but the clarity is still high.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each serving a distinct purpose: action description, post-condition, alternative tool, sync warning, and example. It is front-loaded with the core purpose and avoids redundancy, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description covers all essential aspects: purpose, effect, return value, sync behavior, and an example. It also links to the complementary tool, providing complete context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the parameter with 100% description coverage. The description adds an example usage call, reinforcing that `id` is required and providing context. This adds value beyond the schema, justifying a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb 'Remove' and resource 'alarms/notifications', clearly stating the tool's action. It also distinguishes from sibling `task_set_alarms` by directing users to that tool for adding alarms, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 clear alarms) and points to `task_set_alarms` as the alternative for installing new alarms. It also warns that mutations don't sync automatically and advises calling `sync_trigger` for cross-device visibility, providing comprehensive usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explicitly states 'No side effects: read-only by contract — never mutates OmniFocus.' This goes beyond the lack of annotations by clarifying the tool's safety and describing the return format (description and plannedChanges).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no redundancy. Front-loaded with core purpose, then safety note, then usage example. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the lack of output schema, the description clearly states what it returns and its role as a dry-run. It covers all essential aspects: purpose, safety, usage pattern, and relation to sibling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to repeat parameter details. It mentions the tool accepts the same arguments as task_create, which adds context but doesn't elaborate beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it previews task_create without changes, distinguishes from the sibling tool by warning to use task_create for actual creation. Verb 'Preview' and resource 'task_create' 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly says when to use (as a dry-run) and when not to (use task_create for actual creation). Provides workflow: pass same args, inspect plannedChanges, then call the write tool. Offers clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adequately discloses side effects: it writes the resolved deferDate via task_update, triggers a sync, and supports idempotency, concurrency control, and dry_run. It also returns resolvedDeferDate and reason. However, it does not explicitly state that it is a write operation or detail all possible error states, but it is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that front-loads the primary purpose, then systematically covers variants, environment variables, exclusions, return values, side effects, safety features, and an example. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 explains the return object (taskId, resolvedDeferDate, reason). It covers side effects (writes, sync), safety (dry_run, idempotency, expectedModifiedAt), and provides an example. The sibling tools list includes task_update and batch variants, which are adequately addressed by the 'when not to use' note.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, but the tool description adds value by explaining the high-level intent concept for the 'intent' parameter, listing all variants, and noting environment variables for defaults. This exceeds what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool defers a task to a date computed from a high-level intent, with specific verb 'Defer' and resource 'task'. It distinguishes from unconditional ISO-date defers by explicitly saying to use task_update instead, and lists multiple variants, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool (for smart defer based on intent) and when not to (for unconditional ISO-date defers, prefer task_update). It enumerates intent variants and gives an example, offering clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even without annotations, the description fully discloses the tool's behavior: it is read-only, causes no side effects, and never mutates OmniFocus. It also describes the output structure ({description, plannedChanges}) so the agent knows what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences plus an example. Every sentence adds value, and it is front-loaded with the core purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, 2 required) and lack of output schema, the description sufficiently explains the return value and side-effect behavior. It covers what the agent needs to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with parameter descriptions, so the description adds little extra semantic value beyond stating to 'pass the same args you would to the write tool'. This is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 a deletion without making changes. It uses specific language ('Preview what task_delete would do without making any changes') and differentiates itself from the sibling tool task_delete by explicitly warning not to use it for actual deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to use this tool (dry-run companion) and when not to (do not use for actual deletion, use task_delete instead). It also provides an example workflow: pass same args, inspect plannedChanges, then call the write tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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: dryRun=false creates tasks, and suggests sync_trigger for cross-device. Mentions path-mode constraints and size cap. However, lacks details on error handling or rollback.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with purpose, then covers usage, parameters, constraints, alternatives, side effects, and 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, no output schema, and no annotations, description covers core behavior, parameter meanings, and side effects. Lists return fields but could elaborate on error conditions. Overall fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant context: explains two-phase workflow, default values, path-mode restrictions, and attachSourceTo modes. Provides example with parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Capture tasks from an image' and distinguishes from sibling tool task_batch_create by noting not to use when structured tasks exist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (have image) and when not (already structured tasks). Details the two-phase process with dryRun and confirmation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully details behavior: read-only vs create, no auto-sync, two-phase contract with return shapes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured, front-loaded with primary action, each sentence adds unique value, includes example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description provides expected return shapes, covers all use cases, and includes side effects and an example.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions; the tool description adds context on return values but not significant new parameter meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool splits prose into candidate tasks with provenance, and explicitly distinguishes from sibling task_batch_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (wall-of-text) and when-not-to-use (structured tasks, call task_batch_create instead), plus the two-phase contract.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses idempotency (returns noChange), side effects (reparents, sets syncPending), and response format. It lacks auth/permission info but is otherwise thorough for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Six sentences, front-loaded with purpose, then guidelines, then details. Every sentence provides unique value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description includes return format details. Covers all essential behavioral aspects for a moderate-complexity tool with three destination types. No annotations, yet description is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage. Description adds 'Exactly one destination must be specified: projectId, parentId, or toInbox: true,' reinforcing mutual exclusivity beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Move an OmniFocus task to a new location — a different project, another task (as a subtask), or the inbox.' This is a specific verb-action with resource and scope, distinguishing it from siblings like task_reorder 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Do NOT use task_move to reorder siblings within the same parent (task_reorder handles that); prefer task_update when you only need to change editable fields, not reparent.' This provides clear when-not-to-use and alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It explicitly states 'No side effects: read-only by contract — never mutates OmniFocus' and 'Preview what task_move would do without making any changes', fully disclosing the read-only behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with clear front-loading of purpose. Every sentence adds value, including an example workflow. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 shape ({ description, plannedChanges }). Covers side effects, usage workflow, and behavioral contract. Complete for a simple preview tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 minimal parameter-specific detail beyond the schema, though it implies parameters match those of task_move. No deeper semantic guidance provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 task_move would do without making changes. It explicitly distinguishes from the actual move tool (task_move) and specifies the return format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (preview) and when-not-to-use (do not use to actually move). Names the alternative tool (task_move) and describes a complete workflow: pass same args, 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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits: returns projects in input order, omits missing IDs with warnings in meta.warnings, and states it is read-only and safe to retry. For the maxOutputBytes parameter, it explains truncation behavior in detail, which is not obvious from the schema alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the core purpose, followed by usage guidelines, behavioral notes, and an example. No extraneous information; every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately explains the return type (Project[] in input order) and mentions meta.warnings for missing IDs. The fields parameter and maxOutputBytes are well-described. Minor gap: it doesn't explicitly state that the 'fields' parameter affects each returned project's shape, but this is implied by the parameter description. Overall, the tool is well-documented for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the two parameters (ids and fields), so baseline is 3. However, the description adds significant value beyond the schema: it clarifies the purpose of 'fields' (restrict returned fields), explains the behavior of maxOutputBytes (truncation, progress guarantee), and provides an example. This additional context justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool fetches up to 100 projects by persistent ID in a single round-trip, distinguishing it from project_get (single ID) and project_list (all projects). The verb 'Fetch' and resource 'projects by ID' are specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (multiple IDs) and when not to (single ID, recommending project_get instead). Includes an example usage, making the guidance concrete and easy to follow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers all behavioral traits: null resets to interval-derived schedule, past-dated values accepted and cause overdue, side effects (writes, cache invalidation, syncPending), errors (NOT_FOUND), and 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Each sentence adds value; front-loaded with action and usage. Slightly verbose in explaining null behavior and return details, but overall well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description details the return structure, errors, side effects, and includes examples. Fully complete for a 2-param mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). The description adds context for the null behavior of nextReviewDate and past-date acceptance, improving semantic understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Set or reset a project's next review date directly' and distinguishes from related tools like review_mark_reviewed and review_set_interval, providing a clear verb+resource+scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'when to use' (reschedule independent of interval) and 'when not to use' (do not use for marking reviewed or changing interval) with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully covers behavioral traits: it details that only supplied fields are changed, null clears specific fields, side effects include writing to OmniFocus and setting meta.syncPending, and the return value includes updated status. It also explains concurrency guard via expectedModifiedAt and idempotency via idempotency_key.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the main purpose, then clearing mechanism, usage restrictions, safety controls, return value, and examples. It is front-loaded with key information. While slightly long, every sentence contributes value; minor redundancy could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count (17) and no output schema, the description is thorough: it covers update mechanics, safety controls, side effects, return value structure, and references sibling tools for other operations. It also explains concurrency and idempotency, making the tool's behavior fully understandable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 how to clear fields (pass null), aliases for status ('paused' → on-hold), and preference for note over noteHtml. It also provides examples that clarify parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as 'Partially update mutable fields on an OmniFocus project' and distinguishes it from creation/deletion tools by explicitly stating 'Do NOT use to create or delete projects; prefer project_create or project_delete instead.' The verb 'update' combined with the resource 'project' is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool (partial updates) and when not to (create/delete), with named alternatives. It also explains safety controls like dry_run and expectedModifiedAt, giving clear context for correct invocation in different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares safety: 'safe to call repeatedly; no side effects.' Discloses cursor pagination constraint (must use identical filters). No annotations to contradict, but description adds behavioral context not in schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two main sentences plus two examples. Front-loaded with purpose. Every sentence adds value. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains return type (tasks[] with pagination), safety, and filter capabilities. Could mention meta fields from maxOutputBytes, but schema covers that. Good coverage for 11-parameter tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, so baseline 3. Description adds value by summarizing filters ('project, tags, flagged, completion status'), explaining pagination cursor constraints, and giving examples. Slight improvement over schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear statement: 'Full-text search across OmniFocus task names and/or notes.' Verb 'search' + resource 'tasks' + scope. Distinguishes from sibling task_get by explicitly advising against use when ID is known.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when to use ('when you don't know the ID') and when not to ('Do NOT use when a known task ID is available'). Provides alternative (task_get). Examples show typical usage with filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return value (persistent ID) and sync behavior. No annotation contradictions. Could mention idempotency but not required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five clear sentences with examples. Front-loaded purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers return value, sync trigger, parent nesting, and provides examples. Complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions, and the description adds examples and notes on parentId usage, enhancing understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifically says 'Create a new tag in OmniFocus' and distinguishes from moving by advising 'Do not use to move an existing tag; prefer tag_move instead.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when not to use (moving) and provides alternative (tag_move). Also mentions getting parent IDs from tag_list and triggering sync.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effects: writes deferDate, dry_run skips writes, triggers sync on success, per-entry failures do not abort others. With no annotations, description fully covers behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise two sentences plus example. Front-loaded: declares batch variant, array input, independent resolution. Usage guidance, return format, side effects, and example are succinctly included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes return format, error handling, side effects, and dry run. Lacks explicit mention of idempotency key behavior, but schema covers it. Adequate given complexity and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). Description adds meaning for 'entries' (per-entry failures inline) and 'dry_run'. Does not mention 'idempotency_key', but schema already describes it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly identifies as batch variant of task_defer_smart with specific verb 'accepts an array of { taskId, intent } and resolves each intent independently'. Distinguishes from sibling task_defer_smart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 this for a single task — prefer task_defer_smart') and explains when to use (batch of multiple tasks). Covers triggers and dry run behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses irreversibility ('IRREVERSIBLE'), the confirm guard, atomic validation, best-effort execution, side effects (writes, syncPending), and return format. It provides complete behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose first, then warnings, behavior, guidance, return format, side effects, example. Every sentence is informative. Slightly lengthy but not repetitive, earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a batch delete tool, the description covers all necessary aspects: when to use, prerequisites, behavior (atomic validation, best-effort), return format (including task name for agent to describe), side effects, and sync guidance. It is complete for an agent to invoke correctly without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 reinforcing the confirm requirement, explaining the best-effort semantics per item, describing the return structure with captured task name, and giving an example. This goes beyond the schema, justifying a score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Permanently delete many OmniFocus tasks in a single JXA round trip.' It also distinguishes from sibling tool 'task_delete' by explicitly stating preference for batch use when deleting more than one task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Prefer this tool over repeated task_delete calls whenever deleting more than one task.' It also sets prerequisites (confirm=true), explains validation atomicity and best-effort execution, and mentions side effects with sync trigger recommendation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description covers all behavioral traits: idempotency, side effects (sets completedAt and meta.syncPending), return values with name field, and the clarification-needed response for incomplete children.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: starts with main action, then details, then examples. Slightly verbose but every sentence adds value. Could be trimmed slightly but remains clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description fully explains return values. Handles complex cases like incomplete children. References the sibling `clarify` tool. No gaps in understanding the tool's complete behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by explaining default behavior for `at` and providing two concrete examples, clarifying usage beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Complete an OmniFocus task — marks it done with a completion timestamp.' The verb and resource are explicit, and it distinguishes from siblings like task_delete or task_drop by warning not to use for deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: when incomplete children exist, use the `clarify` tool; do not use for dropping/deleting. Also mentions idempotent behavior and returning noChange if already completed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully discloses behavioral traits: side effects (creates task, sets meta.syncPending = true), idempotency replay behavior, return value format ({ id, name } with name echo), and when sync_trigger is needed. This exceeds typical transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose first, then placement rules, bulk warning, safety, return value, side effects, and examples. It is slightly long but efficient, with every sentence adding value. Front-loading is good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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, the description covers all critical aspects: placement options, idempotency, return format, side effects, and syncing. It leaves no major gaps for this mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context: clarifies mutual exclusivity of projectId/parentTaskId, explains dueDateFloating behavior (time zone following), and details idempotency_key effect. This goes beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource ('Create a new task') and distinguishes the three placement options (inbox, project, subtask). It also explicitly calls out the sibling tool task_batch_create for bulk creation, establishing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Supply exactly one of: projectId, parentTaskId, or neither (inbox).' It also advises against bulk creation and points to task_batch_create. Additionally, it explains idempotency key usage for safe retries and mentions side effects with sync_trigger.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: which fields copy over (name, note, defer/due dates, etc.), which regenerate (id, timestamps), that completed/dropped state is not carried, side effects (creates task, sets syncPending), and the return value structure. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-organized: main purpose first, then details, warnings, return value, and examples. Each sentence serves a purpose, though it could be slightly more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (recursive duplication, multiple destination options, no output schema), the description is exceptionally complete. It covers all behavioral aspects, side effects, return fields, and gives two concrete examples. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value: it explains the default placement ('alongside the source'), the constraint on destination ('exactly one of projectId, parentId, or toInbox: true'), and provides examples for common cases. This goes beyond the schema schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource ('Duplicate an OmniFocus task') and immediately clarifies the recursive option. It also explicitly distinguishes from siblings like task_move and task_create, making the tool's unique purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-not-to-use guidance: 'Do NOT use task_duplicate as a substitute for task_move (which reparents the existing task) or task_create (when the new task's fields differ from the source).' It also explains default placement and destination options with concrete rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effects (writes to OmniFocus, sets syncPending), requires sync_trigger for visibility, explains dry-run vs apply phases, and failure conditions like confirmation mismatch. No annotations present, so description carries full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single well-structured paragraph covering all key topics. While thorough, it is somewhat lengthy but front-loaded with essential concepts. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complex predicate AST, two-phase protocol, and no output schema, the description completely covers input constraints, behavior, side effects, exclusions, and provides an example. Agent has sufficient information to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 by explaining the dry-run default, confirmation echoing requirement, and predicate AST structure, enhancing understanding beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'Predicate-driven bulk task reclassification' with a two-phase contract. It distinguishes itself from sibling tools like task_batch_update by explicitly saying not to use it when explicit task IDs are known.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (predicates, bulk) and when not to (explicit IDs), with direct alternative (task_batch_update). Also explains the two-phase contract, match cap, and confirmation requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: atomic replacement, requirement for task dates when using relative kinds, return of updated task, and the fact that mutations do not sync automatically (requires sync_trigger for cross-device visibility). It also notes that empty array is equivalent to task_clear_alarms. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph that includes the action, behavior, alternatives, error cases, and two examples. Every sentence contributes necessary information without redundancy, and it is appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 parameters, no output schema, no nested objects, no annotations), the description is largely complete. It covers inputs, behavior, errors, alternatives, and syncing. A minor gap is that it doesn't detail the structure of the returned 'updated task', but given the absence of an output schema, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 extra value beyond the schema by explaining the equivalence of empty array to task_clear_alarms, detailing the three kinds of alarms with examples, and clarifying the offsetSeconds sign meaning. This additional context justifies a score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Replace the alarm/notification set on an OmniFocus task atomically', specifying the verb 'replace' and the resource 'alarm/notification set on an OmniFocus task'. It distinguishes from the sibling tool 'task_clear_alarms' by noting that an empty array is equivalent, and provides examples showing usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use the tool (to replace alarms), mentions the alternative 'task_clear_alarms' for removing all alarms with no payload, and states the error condition where relative kinds require the task to already have the corresponding date set, returning a VALIDATION error. This provides clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature, absence of URLs/secrets in output, environment variable requirement (OMNIFOCUS_WEBHOOKS_ENABLED=1), and return order. Fully transparent about all behavioral traits beyond what schema or annotations (none) provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with front-loaded purpose, but contains several sentences that could potentially be condensed. Still efficient and earns its length with useful details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 covers return format, order, safety characteristics, and configuration requirement. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist in schema (0 params), so baseline is 4. Description adds no parameter info, but none is needed. No improvement possible.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists webhooks by name, trigger, and createdAt. It distinguishes from sibling tools like webhook_delete and webhook_register, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use (confirm wired-up webhooks) and when not to (retrieve URLs/secrets). References alternative tool webhook_delete. Provides clear context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully covers behavior: read-only, safe to retry, explains return values (including null/empty cases), and lists error conditions. No hidden traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose first, then usage guidance, return details, errors, and example. Slightly verbose with example, but each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description covers purpose, usage, return format, errors, and read-only nature. Complete and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so schema coverage is 100%. Description explicitly confirms 'Takes no arguments,' which adds clarity beyond the empty schema. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads the active perspective and focus container. It distinguishes from sibling tools like window_set_* and perspective_evaluate, making its unique purpose evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (to know current view, confirm prior set), when not to use (for data evaluation), and gives context for pair-assistant flows vs headless agents. Also provides alternative tool perspective_evaluate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effects: writes to OmniFocus, sets syncPending = true. Notes that the return field 'name' may be null if the project was deleted between write and read. With no annotations provided, the description fully bears the 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet thorough: front-loaded with purpose, then usage, return format, side effects, and example. No wasted words; every sentence serves a clear function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully documents the return shape. Covers purpose, usage, side effects, and example, making it complete for a simple one-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is sufficiently described in the schema. The description adds value by reinforcing the context ('when you have a project id') and providing an example usage, justifying a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it is a convenience alias for review_mark_reviewed, marks a single project as reviewed, and sets dates. Distinguishes itself from sibling tools like review_list_due and review_mark_reviewed by specifying its specific use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when you have a project id and want a single-call review operation') and when not to use ('Do not use to list projects due for review'), providing a named alternative (review_list_due).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature, safe to retry, return structure with fields, sorting order, and edge case (empty array when no Templates folder). No annotations provided, so description carries full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences plus example, no wasted words. Purpose, exclusion, return format, and behavior are front-loaded and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no annotations or output schema, the description covers purpose, behavior, return format, sorting, edge case, and provides an example. Fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; description adds value by explicitly stating 'call with no args' and giving an example. Schema coverage is trivially 100%, baseline 3; description provides helpful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states listing saved project templates, distinguishes from ordinary projects, and explains what counts (templates with parseable fence).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly warns not to use for ordinary projects and names the alternative tool (project_list). Clear when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description fully compensates by detailing side effects (writes to OmniFocus, sets syncPending = true) and potential edge cases (name being null if project deleted). The return shape 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (~70 words) and well-structured: front-loaded purpose, usage guidelines, return info, 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no output schema, and no annotations, the description is remarkably complete. It covers purpose, usage, return values, side effects, and an example, making it self-contained for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of the id parameter. The tool description adds an example usage, which provides context for how the parameter is used, slightly enhancing semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool marks a project as reviewed, setting lastReviewDate to now and advancing nextReviewDate by the review interval. It distinguishes itself from review_set_interval by explicitly noting it should not be used to change the interval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use after completing a weekly review, and do not use to change the review interval, with a clear alternative (review_set_interval). This helps the agent decide when to invoke the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description fully covers behavior: read-only, no side effects, returns lastSyncAt and inFlight, with note that lastSyncAt is null if never synced. Gives example usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: 3 sentences, front-loaded with main purpose, no wasted words. Every sentence provides essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely adequate for a zero-parameter tool with no output schema. Addresses common confusion with sync_trigger, explains output format, and provides usage context. No missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, baseline 4. Description adds value by specifying return fields (lastSyncAt, inFlight) beyond schema. Could hint at expected input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the last sync state without triggering a new sync, and distinguishes it from sync_trigger by explicitly naming the alternative. The verb 'return' and resource 'sync state' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says not to call this to initiate a sync and directs to use sync_trigger instead. Also explains when to use: to check whether a previous sync completed before querying cross-device data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description thoroughly covers behavioral traits: atomicity (best-effort per-item), success conditions, failure reporting with prefixes, return format, side effects (writes to OmniFocus, syncPending), and tag diff resolution logic. This compensates fully for the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured front-loading the primary purpose, then schema details, behavioral notes, and example. Every sentence provides necessary information without redundancy, making it efficient for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains the return format (assigned and failed arrays with detailed components), side effects, and idempotency handling. It includes an example and covers all aspects needed for correct invocation, leaving no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions, so baseline is 3. The description adds value by explaining the interaction between addTagIds and removeTagIds (remove wins, no-op for same tag) and the overall batch behavior, which is not captured in the schema. This additional context justifies a score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies inbox-triage style assignments to many tasks in one batch, specifying the actions (move to project, diff tags, set defer/due/flagged). It distinguishes from sibling task_batch_update by noting a tighter schema and designated use for the inbox-triage prompt's confirm step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use and when-not-to-use: 'Do NOT use this tool for full task replacement — use task_update or task_batch_update for those. Prefer task_batch_assign over a sequence of single task_update calls when you have a confirmed triage plan.' Also mentions it is designed for the inbox-triage confirm step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses atomic validation (whole batch rejected on any schema failure), best-effort execution (per-index success/failure), response format with per-index outcomes, side effects (writes to OmniFocus, sets meta.syncPending), and need to call sync_trigger for cross-device propagation. No annotations exist, so description fully handles transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Approximately 120 words, front-loaded with purpose, each sentence adds necessary detail without redundancy. Structure flows logically: purpose, validation, execution, preference guidance, parameter format, contrast with sibling, return format, side effects, example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description fully explains return structure with completed/failed arrays, and the value includes task name to avoid follow-up reads. Covers validation atomicity, execution best-effort, side effects, and sync dependency. Complete for a batch mutation tool with no annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by explaining the items structure with 'at' as optional ISO-8601 timestamp defaulting to now, and provides a concrete example. The idempotency_key parameter is less elaborated but schema covers it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool marks many tasks complete in a single round trip, distinguishing it from repeated single-task completions. The verb 'mark complete' and resource 'tasks' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to prefer this tool over repeated task_complete calls for multiple tasks. Also contrasts with task_complete for idempotent handling of already-completed tasks, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, description fully discloses atomic validation, best-effort execution, per-index outcomes, side effects (writes to OmniFocus, sets syncPending), return format with task names, and need to call sync_trigger for cross-device changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph with front-loaded purpose, then details. No redundant words. Each sentence adds new information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema or annotations, description provides complete picture: purpose, behavior, return format, side effects, example. Sufficient for agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters fully (100% coverage). Description adds value by explaining idempotency key behavior (replays within TTL return cached envelope) beyond schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it cancels (drops) many OmniFocus tasks in a single JXA round trip. Distinguishes from sibling tools like task_batch_delete and task_drop by specifying batch nature and permanence difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to prefer this over repeated task_drop calls when dropping more than one task, and clarifies to use task_batch_delete for permanent removal. Also explains atomic validation and best-effort execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: atomic validation, best-effort execution, per-index outcomes, side effects (writes to OmniFocus, sets meta.syncPending), and return format. It also explains the failure modes and suggests calling sync_trigger for device sync.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise. It front-loads the core purpose, uses bullet-like sentences, and includes every piece of essential information (validation, execution, alternatives, unsupported features, return format, side effects, example) without waste. Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a batch update tool with a nested parameter and no output schema, the description covers all necessary aspects: input format, validation model, execution semantics, unsupported fields, return structure, side effects, and integration with sibling tools. It is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 listing the supported fields in patch, explicitly stating what is not supported (addTags, removeTags, etc.), and providing a concrete example. This goes beyond the schema's descriptions and helps the agent understand the relationship to task_update.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Partially update many OmniFocus tasks in a single JXA round trip.' It clearly distinguishes from siblings like task_update by stating 'Prefer this tool over repeated task_update calls whenever you are updating more than one task.' The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (for updating more than one task) and when not to use it (fall back to task_update for additive tag diffs and safety primitives). It names the alternative tool and provides clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the task becomes one-time, returns updated task with null repetitionRule, and that mutations don't sync automatically, requiring sync_trigger for cross-device visibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with no fluff. Front-loaded with purpose, includes an example, and covers all essential aspects in a few sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 and no output schema, the description covers purpose, behavior, result, side effects, and syncing adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes id with pattern and description. Description adds value by telling the agent where to get the id ('Get from task_list or search_query'), which is helpful beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and the resource 'repetition rule from an OmniFocus task'. It distinguishes from sibling task_set_repetition by explicitly naming it for setting/changing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (remove repetition rule) and when not to (use task_set_repetition for setting/changing). Also provides syncing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully covers behavioral traits: it explains side effects ('removes the task from the task list and adds a project; sets meta.syncPending = true'), automatic transfer of subtasks/notes/tags/dates, and return value structure. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive: every sentence adds value, it front-loads the primary action, and includes examples at the end. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of conversion and no output schema, the description thoroughly explains the return value, side effects, and usage context. Sibling tools are numerous but this tool is well differentiated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is 100% covered, so baseline is 3. The description adds value by providing example usage with parameters and explaining the role of folderId and position beyond the schema, though it doesn't repeat default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Promote an OmniFocus task to a first-class project' using a specific verb and resource. It distinguishes itself from sibling tools like task_move and project_create by explicitly contrasting when not to use them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('when a task has grown in scope') and when-not-to-use guidance ('Do NOT use on tasks already in a project – use task_move instead; use project_create when starting from scratch'), offering clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses all behavioral traits: it is read-only, has no side effects, no model calls, uses a deterministic lexical scoring algorithm, excludes completed tasks by default, supports optional scope narrowing, returns sorted candidates, and describes the output format including empty result handling. It even notes performance optimizations (batch queries).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it opens with the core purpose and algorithm, then usage guidelines, parameter details, output format, and a performance note. Every sentence adds value without redundancy. Despite being moderately long, it is efficiently organized and front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 5 parameters including a nested scope object, a custom scoring algorithm, and no output schema, the description provides comprehensive coverage. It explains input semantics, the algorithm, output format (including field descriptions), default behaviors, and error cases. The agent can fully understand how to use the tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant semantic value beyond the schema: it explains the scoring algorithm, the role of 'note' as a tiebreaker, the mutual exclusivity and purpose of 'scope', the default for 'includeCompleted', and provides examples. While the schema already documents each parameter, the description enriches understanding of how they interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is a 'Lexical nearest-neighbour search for de-duplicating tasks.' It specifies the verb (search/find), the resource (tasks), and distinguishes from siblings like task_search and task_find_by_name by explicitly stating the deduplication use case. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use BEFORE task_create when you suspect a duplicate' and 'Do NOT use this tool for general full-text search — call task_search for that.' It also mentions alternatives like task_find_by_name, giving clear when-to-use and when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature, safe to retry, and explains behavior of includeSubtasks, notePreviewChars, verbose, fields, and includeLinks. Covers return value structure and truncation details. No annotations provided, so description fully handles transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with purpose and key guidance. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a single-task fetch: covers all parameters, return values, and edge cases like note truncation. No output schema, but description adequately explains expected response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline is 3. Description adds usage context beyond schema, e.g., how includeSubtasks relates to task_get_many, and note truncation behavior. Slightly exceeds baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a single OmniFocus task by persistent ID, with a specific verb and resource. It distinguishes from sibling tools like task_get_many by explicitly stating not to use for multiple IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use (known task ID, need full detail), when not to use (multiple IDs, use task_get_many instead), and when to use includeSubtasks (only if subtask detail needed, otherwise use task_get_many).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description takes full burden. States 'Read-only; no side effects.' Mentions return warnings for unparseable dates, disclosing error handling. Behavior is fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Compact yet comprehensive, covering purpose, syntax, usage note, return fields, read-only note, and example with no superfluous content. Front-loaded with key points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description enumerates all return fields. Addresses input format, dependencies (tag_list), and side effects. Complete for a single-parameter parse tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema with 100% coverage already describes 'text' parameter; description adds context about line-by-line parsing and project prefix syntax, enhancing meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States clearly: 'Parse OmniFocus transport text DSL into structured task objects — no tasks are created.' Lists supported tokens and explicitly distinguishes from task creation, making purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises not to use for creation and directs to pass returned tasks to task_create. Also instructs to resolve raw tag/project names with tag_list. Provides clear when-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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side-effect-free nature ('safe to call repeatedly; no side effects'), pagination behavior, case-insensitive substring matching, and scope usage. No annotations provided, so description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose first, then filter details, examples. Slightly verbose but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers search behavior, pagination, filters, constraints, and examples despite no output schema. Adequate for a 12-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds context beyond 100% schema-covered parameters: explains optionality of q, scope interaction, required filter combinations, and pagination defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'search', resource 'tasks', and distinguishes from sibling tool task_get: 'Do NOT use when you already have an ID — prefer task_get instead.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when to use (keyword and/or structured filters), when not (if ID known, use task_get), and required conditions: 'At least one of q, projectId, tagIds, available, dueBefore, or dueAfter must be provided.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description bears full burden. Discloses partial update behavior, side effects (writes to OmniFocus, meta.syncPending), safety controls, tag mode mutual exclusivity, and concurrency guard. Thoroughly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose first, then exclusions, tag modes, safety controls, examples. Every sentence is meaningful. No fluff despite length. Front-loaded with essential info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 18 params, no output schema, description covers purpose, exclusions, tag behavior, safety controls, side effects, concurrency, and example usage. Adequately complete for a complex mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, so baseline 3. Description adds context by explaining tag update modes, safety controls, and alias (setFlagged). Provides examples. Adds value beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Partially update mutable fields on an OmniFocus task' and distinguishes from siblings by explicitly advising against using this for complete/delete, pointing to task_complete/task_delete. Also explains two tag-update modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance, naming alternatives. Explains tag modes, safety controls (dry_run, expectedModifiedAt, idempotency_key), and side effect of sync_trigger. Comprehensive context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description bears full burden. It discloses HTTPS POST with HMAC/retry/circuit-breaker, off-by-default, side effects (outbound POST), return values, and that 'delivered' means attempted delivery only. Also references ADR for logging behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is efficiently structured with purpose first, followed by operational details, warnings, return info, notes, and example. No filler; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter testing tool with no output schema, the description covers all necessary aspects: purpose, mechanics, prerequisites, constraints, return format, side effects, and an example. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds example usage and clarifies the parameter's role beyond the schema description. While not necessary, the example enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fires a synthetic event through a registered webhook to verify wiring. It distinguishes from sibling tools like webhook_register and webhook_list by focusing on testing. The verb 'fire' and resource 'webhook' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (verify webhook wiring) and when not to use (load testing). Mentions prerequisite environment variable. Does not require alternative tool mention as siblings are distinct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, but description fully discloses UI-affecting nature, side effects (visible window changes, no cache invalidation), errors (OF_WINDOW_UNAVAILABLE, OF_NOT_FOUND), and 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, though slightly verbose. Every sentence adds value, including warnings, usage, and examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return format ({ perspectiveName }). Covers parameter details, errors, side effects, and usage context completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers perspectiveName with description; description adds case-sensitivity, built-in name list, and example, exceeding schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool switches the front OmniFocus window to a named perspective, listing built-in names and custom perspectives. Distinguishes from perspective_evaluate for evaluating results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (user requests like 'show flagged tasks' or guided review) and when not (headless agents), with alternative perspective_evaluate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description compensates fully by stating 'Safe to call repeatedly; no side effects.' and describes return value format including null case.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: purpose stated first, then usage guidance, then feature note, then return description, then example. No superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only 1 required parameter and no output schema, the description covers all needed context: what it does, when to use, return format, and safe calling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and baseline is 3, but description adds value by explaining where to get the ID ('Get the tag ID from tag_list') and includes an example call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get the geographic location trigger currently set on a tag, or null if none.' Uses specific verb and resource, and distinguishes from sibling tool 'tag_set_location'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Do not use to set or clear a location; prefer tag_set_location instead.' Also provides prerequisite: 'Get the tag ID from tag_list.' And notes feature availability: 'OmniFocus Pro feature.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes missing ID handling, read-only nature, safety to retry, and max limit, fully disclosing behavioral traits despite no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise paragraph with front-loaded purpose and efficient sentences covering all critical aspects without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete description covering input, behavior, edge cases, and return format for a 3-parameter tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds context beyond schema with example, ordering, and explanations for all three parameters, despite 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly specifies 'Fetch up to 100 tags by persistent ID' and distinguishes from tag_get, giving specific verb and resource with differentiation from sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (set of IDs needing full objects) and when not to (single ID, use tag_get instead), providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return values (updated tag's ID and new parentId), sync triggering, and promotion behavior. No annotations to contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with no extraneous information. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers input, behavior, output, and side effects for a simple move operation. No missing pieces given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds context beyond schema: id from tag_list, parentId null for promotion, and examples. Schema coverage is 100% but description enriches it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Move a tag to a new parent, or promote it to a root tag' and contrasts with rename. Includes examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (move/promote) and when not (rename), recommends tag_update, and tells to get IDs from tag_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Fully discloses irreversible behavior, return format, side effects (removes from OmniFocus, sets syncPending), and suggests sync_trigger for device synchronization. No annotations to contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured, front-loaded with critical warnings, each sentence serves a distinct purpose, and examples are included without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all important aspects: irreversibility, alternative, required parameter, safety options, return values, side effects, and sync guidance. Very thorough for a deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant value beyond the schema by explaining confirm as mandatory, dry_run as preview, idempotency_key for retry safety, and expectedModifiedAt for concurrency control. Provides realistic examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it permanently deletes a task, emphasizes irreversibility, and distinguishes from the sibling tool task_drop which offers recoverable deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use task_delete vs task_drop, emphasizes that explicit user intent is required, and mandates the confirm parameter with dry_run and expectedModifiedAt as safety controls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully covers behavior. Discloses side effects (changes sibling order, sets meta.syncPending = true), return structure, and the fact that OmniFocus has no numeric sibling index. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear, front-loaded purpose. Each sentence adds value: purpose, constraint, sibling differentiation, return format, side effects, examples. No redundant or vague statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema and complex parameters, the description covers all essential aspects: return values, side effects, constraints, and examples. It is fully self-contained and leaves no major gaps for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). Description adds significant value by explaining the three positioning forms (before, after, at+in) and that exactly one must be set, plus two examples. This goes beyond the schema's individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Reorder an OmniFocus task among its siblings' with a specific verb and resource. It explicitly distinguishes from 'task_move' by noting that reparenting is handled by that sibling tool, making the differentiation strong.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use ('reorder among siblings') and when not to use ('Do NOT use to reparent'), along with the alternative ('prefer task_move'). Also states the constraint that exactly one positioning form must be set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully carries the burden. It discloses side effects: writes tag + note, sets meta.syncPending = true. It also explains round-trips through task_get and the return format. No hidden behaviors omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: starts with purpose, then details of behavior, then usage guidelines, then return value and side effects. Every sentence adds value, no redundancy. Appropriate length for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and five parameters, the description covers all necessary aspects: purpose, parameters, side effects, return format, and usage context. It also mentions the waiting-on resource. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant meaning: explains whom as person/team/system, what as optional short description, since defaults to now and backfill use, followUpAfter drives daysOverdue. Provides an example call. This goes well beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records that a task is waiting on someone/something, tags with @waiting, and writes a structured block. It distinguishes itself from siblings by specifying what it does not do (completion/scheduling) and mentioning related tools like task_clear_waiting_on. The verb 'Record' and resource 'task waiting on' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use to systematize follow-ups' and 'do NOT use for task completion or scheduling,' providing clear when-to and when-not-to guidance. Also mentions the omnifocus://waiting-on resource for surfacing results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully covers behavioral traits: UI-affecting, changes visible window state, no data cache invalidation, return structure, error types (OF_WINDOW_UNAVAILABLE, OF_NOT_FOUND), and side effects. It also warns headless agents should not fire this, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
All sentences are information-dense and purposeful. Well-structured: purpose first, then UI warning, usage guidance, alternatives, parameter detail, return value, errors, side effects, examples. No redundant text; every part earns its place under 10 sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a UI-affecting tool without an output schema, the description is complete. It covers purpose, usage boundaries, parameter semantics, return format, error conditions, and side effects. No gaps remain for an agent to safely use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, but description adds significant meaning: explains that containerId can be a ProjectId or FolderId to set focus, or null to clear. Includes two concrete examples (prj123, null) and clarifies the effect on return value. This far exceeds basic schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it sets/clears the focus container (project/folder) on the front OmniFocus window. It contrasts with siblings like task_list and perspective_evaluate by explicitly stating not to use for filtering data, and notes that headless agents should avoid it. This makes the purpose distinct and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use: when user says 'focus on this project' or for guided flows. Also gives when-not-to-use: headless agents and for filtering task data. Points to specific alternatives (task_list with projectId, perspective_evaluate) that work without affecting UI.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![omnifocus-mcp MCP server](https://glama.ai/mcp/servers/torsday/omnifocus-mcp/badges/card.svg)](https://glama.ai/mcp/servers/torsday/omnifocus-mcp)

Score Badge

Copy to your README.md:

[![omnifocus-mcp MCP server](https://glama.ai/mcp/servers/torsday/omnifocus-mcp/badges/score.svg)](https://glama.ai/mcp/servers/torsday/omnifocus-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/torsday/omnifocus-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server