Things App MCP

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

Annotations provide openWorldHint=true, indicating flexibility in input. The description adds value by disclosing that it supports nested structures and updates (requiring auth-token for updates), which goes beyond annotations. However, it doesn't mention rate limits, error handling, or what happens with invalid JSON. With annotations covering some aspects, a 3 is appropriate for adding useful but incomplete behavioral context.

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

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

The description is appropriately sized with three sentences that each add value: purpose, data format, and update requirements. It's front-loaded with the core function and avoids redundancy. A point is deducted because the last sentence could be slightly more streamlined, but overall it's efficient with zero waste.

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

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

Given the tool's complexity (batch JSON operations with updates), the description is fairly complete: it explains the purpose, data structure, and update logic. With no output schema, it doesn't describe return values, which is a minor gap. However, combined with 100% schema coverage and annotations, it provides adequate context for an agent to use the tool effectively, though more detail on outcomes would improve it.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal param semantics: it mentions 'data' should be an array with 'type' and 'attributes', and implies 'authToken' is needed for updates. This provides some clarification but doesn't significantly enhance the schema's detailed descriptions, meeting the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Create complex projects and to-dos using the Things JSON command. Supports nested projects with headings, checklist items, and to-dos.' It specifies the verb ('Create'), resource ('projects and to-dos'), and method ('using the Things JSON command'), distinguishing it from simpler sibling tools like add-project or add-todo that likely handle single items without JSON complexity.

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

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

The description provides clear context for usage: 'For updates, include "operation": "update" and "id" fields, and provide auth-token.' This indicates when to use this tool (for batch creation/updates via JSON) versus simpler alternatives like add-project or update-todo. However, it doesn't explicitly state when NOT to use it or name specific alternatives, keeping it from a perfect score.

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