Things MCP

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

The description adds meaningful behavioral context beyond the annotations: container deletion can cascade, empty Trash is permanent and global, and separate owner grants are required. It also mentions that global-command gates are disabled, which is useful safety information for an agent deciding whether invocation is appropriate.

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

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

The description is fairly short and front-loaded with the main action, but phrases like 'native verified' and 'global-command gates remain disabled pending their separate checks' are cryptic and do not earn their place. It does not waste many words, but clarity suffers from unexplained jargon.

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

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

Given the destructive nature, multiple action enums, an optional nested target, and a scope revision parameter, the description is not complete enough for reliable invocation. It covers safety consequences and authorization, but omits the meaning of action values, when target is required, and how the revision check works. The output schema helps, but the usage contract remains under-specified.

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

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

Schema description coverage is 0%, and the description does not explain the parameters action, target, requestId, or expectedScopeRevision. It weakly gestures at expectedScopeRevision with 'current scope revision,' but it does not define what each action does, when target is needed, or how requestId should be used. The burden falls entirely on the schema, which is insufficient.

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 says 'Apply a previously reviewed scope using its current scope revision,' which identifies a verb and a resource, but 'apply a scope' is jargon and does not plainly state that this executes destructive operations. The destructive nature is implied by mentions of deletion and empty Trash, but the core purpose remains somewhat vague without relying on the tool name.

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 notes authorization requirements and some destructive consequences, but it never tells an agent when to choose this tool over alternatives like things_preview_destructive or things_trash_item. The phrase 'previously reviewed' hints at a workflow, but there is no explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds a useful behavioral consequence: unavailable features cannot be invoked, which sets the expectation that this tool reveals callable capability status. This complements the annotations without contradicting them.

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

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

Two concise sentences with no filler. The first sentence front-loads the action and scope; the second sentence adds a practical implication. Every word earns its place.

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

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

For a zero-parameter, read-only capability tool with an output schema already present, the description is complete. It tells the agent what to expect, warns that unavailable features cannot be invoked, and leaves return structure details to the output schema.

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

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

The tool has zero parameters, so the input schema places no burden on the description. The description correctly focuses on the output semantics: implementation and verification status of every operation family. This matches the 0-parameter baseline of 4.

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

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

The description uses a specific verb ('Read') and names the exact resource ('implementation and verification status of every operation family'). It clearly differentiates this from the sibling tools by focusing on capability/availability rather than individual item operations or health checks.

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

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

The description implies this tool should be used before invoking operations, since unavailable features cannot be invoked. However, it does not explicitly state when to prefer this over things_health or things_request_status, nor does it name any alternatives or exclusions.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds important behavioral details beyond annotations: segmented scanning semantics, the need to sum partial counts, concurrency caveats, and the offset zero requirement.

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

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

Three tight sentences front-load the core purpose and then provide the key operational constraints. No filler or redundancy.

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

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

For a complex paginated count tool with 17 parameters and an output schema, the description covers the essential scan-loop behavior, concurrency caveat, and offset constraint. It is slightly incomplete because it does not define the filter parameters or explicitly distinguish usage from find_items.

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

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

Schema description coverage is 0%, so the description must compensate. It explains offset and scanOffset indirectly, and defers filter parameter semantics to find. However, most of the 17 parameters are not individually explained, leaving a meaningful gap.

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

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

States a clear verb-resource pair: count matches within a scan segment. It is distinct from find_items (retrieval vs counting) and get_item (single item fetch), so an agent can tell what this tool is for.

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

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

Provides clear operational guidance: follow nextScanOffset, sum counts until scanComplete, and keep offset at zero. It references find for filter semantics, but does not explicitly state when to choose this over find_items or another sibling.

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

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

Annotations already provide readOnlyHint=false and idempotentHint=true, and the description adds valuable behavior beyond them: 'URL receipt confirms dispatch only,' no read-back or returned IDs, and 'never retry with a new request ID.' This aligns with and enriches the idempotency annotation without contradicting it.

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?

Five short sentences are front-loaded with the primary purpose and every sentence earns its place. 'Requires writes' is mildly redundant with the annotation, but the overall density is excellent.

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

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

Despite the deeply nested schema, the description covers the essential dispatch semantics, idempotency constraints, and the critical limitation that there is no read-back or returned ID. Since an output schema is present and annotations carry the safety profile, nothing needed for correct invocation is missing.

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

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

With schema description coverage at 0%, the description compensates by explaining meaningful semantics: the item is a structured to-do or project, checklist rows and initial headings are supported, and requestId carries idempotent retry meaning ('never retry with a new request ID'). It leaves detailed nested fields to the schema, but those field names are self-explanatory.

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

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

The description opens with a specific action and resource: 'Send one structured to-do or project to Things,' and adds distinct capabilities like checklist rows and initial project headings. It does not explicitly differentiate from sibling creation tools such as things_create_item or clarify the 'from_template' name, so it falls short of a 5.

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

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

The description conveys clear context for use—structured to-dos/projects with checklists and headings—but gives no explicit when-to-use versus alternatives or when-not guidance. The retry warning is operational guidance rather than tool-selection guidance.

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

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

The annotations already indicate this is a writing, non-destructive, idempotent operation. The description adds valuable behavioral context beyond the annotations: local write permission is required and disabled by default, and requestId must be unique. This meaningfully informs the agent about preconditions and side-effect profile.

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

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

The description is short and front-loaded with the core operation, which is good. However, the sentence 'Creation of all four kinds is native verified' largely restates the first sentence and adds little new value, making it a redundant sentence in an otherwise compact description.

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 and the large optional parameter set, the description covers the essential entry-point requirements: what can be created, the required requestId, and the permission precondition. It does not cover how parameters should be combined per kind, which limits completeness even though the presence of an output schema reduces the need to describe return values.

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

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

With schema description coverage at 0% and 17 parameters, the description carries a heavy burden but only explains requestId uniqueness and indirectly the kind values. It does not clarify semantic relationships such as areaId vs. projectId applicability, status/dates usage, or when fields are appropriate for each item kind, leaving most parameter semantics underspecified.

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

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

The description uses a specific verb and explicitly enumerates the four resource types ('to-do, project, area, or tag'), making the tool's primary function unmistakable. It does not explicitly contrast itself with siblings like things_create_from_template or things_duplicate_item, so it stops short of full sibling differentiation.

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

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

The description gives clear prerequisites: supply a unique UUID requestId and have local write permission enabled, which is necessary because it is disabled by default. However, it does not state when to choose this tool over alternatives such as create_from_template, update_item, or duplicate_item, so guidance on alternatives is missing.

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

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

Annotations already signal a mutating, non-destructive, idempotent operation, and the description adds substantial behavioral context: the receipt contains the source ID rather than a new item ID, completion is not confirmed, and Things must be inspected before another request. This goes well beyond the structured hints.

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

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

Four terse sentences are front-loaded with the action, then cover prerequisites, an edge case, response behavior, and follow-up instruction. There is no filler; each sentence earns its place.

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

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

For a mutation with an output schema, the description covers purpose, prerequisites, a key exclusion, response limitations, and post-call verification. It would be fully complete with explicit parameter-role explanations, but it is already adequate for an agent that can inspect the schema and sibling tools.

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

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

Schema description coverage is 0%, so the description must compensate, but it only hints at parameters: 'to-do or project' maps to target.kind and 'current revision' maps to expectedRevision. It never explains requestId's role as an idempotency key or the meaning of the optional title field, leaving critical parameters underspecified.

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 opening sentence names the exact verb ('duplicate'), the target resource ('to-do or project'), and the mechanism ('documented URL command'). This makes the tool unambiguous and distinguishes it from siblings like create_item, update_item, and trash_item without needing to open their schemas.

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

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

The description gives actionable prerequisites ('Requires writes, current revision and the local Keychain URL token') and a firm exclusion ('Repeating items cannot be duplicated'). It stops short of explicitly naming alternatives such as create_item for new items, so the guidance is clear but not fully contrasted with sibling tools.

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

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

Annotations already show readOnlyHint=false and destructiveHint=true, but the description adds substantial behavioral detail beyond them: 'Checklist replacement replaces every row,' 'These fields cannot be read back,' 'receipt is unverified dispatch,' and 'Repeat templates may reject these changes.' It also explains the need for current revision and the keychain token. This is exactly the kind of context an agent needs beyond the annotation flags.

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

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

The description is compact and front-loaded with the tool's purpose, followed by necessary prerequisites and behavioral caveats. Every sentence adds useful information. It is slightly dense and grammatically awkward in the opening enumeration, which keeps it from a perfect score.

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

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

Given the complex nested schema, annotations, and presence of an output schema, the description covers the critical operational context: required revision, unrecoverable/unreadable fields, unverified dispatch, and template rejection risk. It omits explicit semantics for projectId and requestId, but the schema and sibling tool names provide enough surrounding context for an agent to invoke it reasonably.

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

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

Schema description coverage is 0%, so the description must compensate. It maps the main change categories to the changes object: checklist replacement/append/prepend, heading placement, and scheduling. However, required parameters like requestId and target are not explained beyond 'current revision' hinting at expectedRevision, and projectId is not mentioned at all. The property names are suggestive, but the description only partially bridges the schema gap.

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

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

The description names a specific set of operations—checklist replacement/append/prepend, heading placement, and scheduling with reminders/Evening/clearing—on Things items. This clearly differentiates it from general tools like things_update_item, though it does not explicitly name an alternative. The verb 'Send' and resource 'To Things' give a clear action and target.

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

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

It states prerequisites: 'Requires writes, current revision and the local Keychain URL token,' and gives caveats like 'Repeat templates may reject these changes.' However, it never explicitly says when to prefer this tool over siblings such as things_update_item or things_schedule_item, so usage guidance is implied rather than explicit.

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

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

The annotations already cover read-only and idempotent safety. The description adds an important behavioral caveat: 'Automation errors are not reported as absence.' This clarifies how false results should be interpreted, which is valuable context beyond the structured annotations.

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

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

Two short sentences with no filler. The primary purpose is front-loaded in the first sentence, and the important error-semantics caveat appears in the second. Every word earns its place.

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

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

For a simple existence-check tool with a rich output schema and strong annotations, the description plus the error caveat is largely adequate. It could be more complete by addressing how this differs from things_get_item, but that gap is more of a usage-guidance issue than a fundamental incompleteness.

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

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

The description names the two parameters ('kind and ID') and indicates their role together as the identity criterion. However, schema description coverage is 0%, and the description does not explain the accepted kind enum values or ID constraints beyond what the schema already provides. It provides minimal added semantic value.

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

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

The description states a specific operation: 'Check whether an item exists by kind and ID.' This clearly identifies the resource and the predicate nature of the tool. It does not explicitly contrast with sibling things_get_item, so it stops short of full sibling differentiation.

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

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

There is no guidance on when to use this tool instead of things_get_item or other item-related siblings. The description implies an existence check but does not explain that it should be used for lightweight verification before actions, nor when get_item would be more appropriate.

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

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

Beyond the readOnly/idempotent/destructive annotations, it discloses that sorting changes only result order, that pagination beyond 5000 objects requires following nextScanOffset with zero offset, and that results are not a snapshot. The 'Fetch before editing' warning further clarifies result staleness.

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

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

Every sentence earns its place: purpose, sorting semantics, pagination rule, and staleness warning. It is front-loaded with the resource and filters, and contains no filler or repetition.

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

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

For a 17-parameter query with an output schema and safety annotations, the description covers purpose, filtering, sorting, pagination, and snapshot behavior. It is missing explicit guidance on count vs. list alternatives and the meaning of includeNotes, but these are minor given the output schema and self-explanatory parameter names.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It maps the main filter parameters (kind, text, status, tagId, date ranges, selected, list, parent) and explains the semantics of sortBy/sortOrder and scanOffset/offset. It doesn't mention limit or includeNotes explicitly, but the schema names and defaults make those mostly self-evident.

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 first sentence names a concrete verb ('Find'), a resource ('items'), and the major filter dimensions (type, text, status, tag ID, date range, selected, list, parent). This distinguishes it from sibling get_item (single item), count_items (counts), and exists (boolean check), so an agent can select it as the list/query tool.

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

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

The description gives practical when-to-use context: it is a read-only find operation and the line 'Fetch before editing' positions it as a precursor to mutation tools. It does not explicitly name alternative tools such as things_count_items for counts, so it stops short of full differentiation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read behavior is covered. The description adds useful behavioral context beyond those annotations by disclosing that the response includes the revision, which is important for the editing workflow. No contradiction with annotations.

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

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

One tight sentence with no filler. The core action and resource are front-loaded, and the revision detail is appended efficiently without repeating schema or annotation information.

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

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

For a simple two-parameter read operation with strong safety annotations and an existing output schema, the description covers the essential workflow: fetch one item by kind and stable id and get its revision for editing. It is slightly short of a 5 because it does not mention not-found/error behavior, but that is a minor gap given the output schema and annotations.

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

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

Schema description coverage is 0%, so the description needs to compensate. It does name both parameters ('kind' and 'stable ID') and adds the useful note that the id is stable. However, it does not elaborate on enum values or id format, though the schema itself provides detailed constraints for those.

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

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

Description states a specific verb ('Read'), a specific resource ('one Things item'), and the lookup method ('by kind and stable ID'). The phrase 'one item' clearly separates it from sibling search/list tools like things_find_items, and the read action distinguishes it from mutation siblings like things_update_item or things_trash_item.

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

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

The phrase 'including its revision for safe editing' gives clear context: this tool should be used when the agent needs the current revision before performing an edit. It does not explicitly name alternatives or state exclusions, so it falls just short of a 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description does not need to restate safety. It adds useful behavioral context by specifying exactly which health dimensions are checked, including the separate Trash permission. There is no contradiction with the annotations.

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

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

The description is a single sentence that front-loads the action and target, with every clause contributing a distinct check. There is no filler or duplication of schema or annotation information.

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

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

For a zero-parameter, read-only, idempotent health check with an output schema available, the description conveys the full scope of the tool. Nothing essential is missing for an agent to understand what this tool covers.

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

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

The tool has zero parameters and the input schema is empty, so there are no parameter semantics for the description to add. The baseline for a no-parameter tool applies.

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

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

The description uses the specific verb 'Check' and enumerates a concrete set of health aspects: connection, timezone, ordinary-write permission, and Trash permission. This makes its purpose distinct from siblings like things_find_items or things_trash_item, though it does not explicitly name an alternative.

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

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

No guidance is given on when to use this tool instead of things_capabilities or things_request_status, and no prerequisites or exclusions are mentioned. The verb 'Check' implies a diagnostic health check, but the selection logic is left entirely to the agent.

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

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

Annotations already indicate destructive and idempotent behavior, and the description adds substantial behavioral context: write permission and latest revision requirements, descendantImpact return semantics, changed-ID counts, and the caveat that counts describe exposed fields rather than every inherited effect. This goes well beyond the structured hints and contains no contradictions.

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

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

The description is dense but not bloated. The main operation is front-loaded, and every subsequent sentence adds a distinct, useful constraint: destination limits, return impact details, permissions, and non-effects. There is no filler.

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

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

For a complex mutation tool with nested oneOf destinations, four required parameters, and an output schema, the description covers the full move matrix, unsupported cases, permission/revision requirements, return behavior, and explicit non-effects. The output schema can carry remaining return-format details, so nothing critical is missing.

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

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

With 0% schema description coverage, the description must compensate, and it does meaningfully: it explains valid target/destination combinations, detach semantics, list restrictions, and the need for the latest revision via expectedRevision. It does not elaborate on requestId, leaving the schema's UUID format to carry that parameter, which prevents a perfect score.

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

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

The description opens with a precise verb and resource: 'Move a to-do to a project or area, a project to an area, detach a parent, or move a to-do to Inbox, Today, Anytime, or Someday.' It enumerates supported move kinds, making the tool's purpose unmistakable and distinguishing it from update, schedule, and trash siblings.

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

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

It provides strong usage context by explicitly listing unavailable moves ('Project Anytime and direct Logbook moves are unavailable') and what it does not do ('Does not reorder items, address headings, or restore Trash'). However, it never names sibling tools such as things_update_item or things_schedule_item as alternatives, so it stops short of a full 5.

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

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

It adds important behavioral context beyond the annotations: the operation requires write permission despite being navigation, and it reports command acceptance rather than confirming creation or cross-device visibility. This meaningfully clarifies side effects and result interpretation without contradicting the annotations.

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

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

Two compact sentences with no filler. The main purpose is front-loaded, and the second sentence adds essential constraints without bloating the description.

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

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

The description covers the tool's general behavior and key limitations, and an output schema exists so return-value details are not required. However, with zero schema description coverage and nested parameter structures, it leaves the relationship between action, target, and list to inference, which is a meaningful gap.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It explains the high-level actions ('show', 'edit', 'quick_entry') and mentions items, built-in lists, and projects, but it never maps specific parameters like target or list to the described behaviors, and requestId remains unexplained.

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

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

The description states a clear purpose: show a built-in list/item, open a task/project for editing, or show Quick Entry on this Mac. It names distinct resources and actions, though it does not explicitly differentiate itself from the similar-sounding sibling things_show_view.

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

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

The description implies when to use the tool: when the agent needs to navigate the Things UI or present Quick Entry. It adds a useful prerequisite (write permission) and a caveat that it only reports command acceptance, but it does not name alternatives or explain when to prefer another sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond that: it never grants permission, cannot enumerate checklist/heading/repeat-template content, lacks atomic scope locking, and requires health checks for native execution gates. These disclosures do not contradict the annotations.

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

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

The description is compact and front-loaded: the first sentence states the operation, then the second adds return/behavior info, and the third adds limitations and gating. Every sentence earns its place; there is no fluff or redundant restatement of the schema.

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

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

With annotations and an output schema present, the description does not need to explain return values in detail, and it covers the tool's purpose and limitations well. However, it is not fully complete because it does not clarify the relationship between the action enum and the target object, which is important for a tool with nested input and conditionally relevant parameters.

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

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

Schema description coverage is 0%, so the description needed to explain action and target semantics. It mentions the three action categories in prose, but it does not map them to the 'action' enum or explain the optional 'target' object, its kind/id fields, or when target is required. This leaves the input semantics under-specified for an agent.

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

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

The description leads with a specific verb ('Inspect') and a concrete resource ('the exposed scope of project/area/tag deletion, emptying Trash, or logging completed items'). It also states it returns a scope revision and never grants permission, which clearly separates it from things_apply_destructive despite not naming that sibling.

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

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

The description gives useful context: this is an inspection/preview operation, not a permission-granting one, and it tells the user to 'Check health for native execution gates.' However, it does not explicitly name the alternative execution tool or state when not to use it, so alternatives are left implied rather than fully specified.

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

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

The description adds value beyond the annotations by clarifying that the check is against a 'local receipt,' not a remote system, and by warning that pending/unknown results should halt further writes. This is useful operational guidance that annotations alone do not convey, though it leaves the exact status vocabulary to the output schema.

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

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

The description is a single, well-structured sentence that front-loads the core action and then provides the important conditional guidance. Every clause contributes meaningful information with no redundancy.

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

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

For a one-parameter, read-only, idempotent status-check tool with an output schema, the description covers the essential purpose, the key semantic of the parameter, and the critical retry guidance. Nothing necessary for correct invocation is missing.

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

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

With 0% schema description coverage, the description must compensate, and it does by explaining that requestId is a mutation request ID tied to a local receipt. This adds meaning beyond the raw UUID format in the schema, even though it does not detail where the ID comes from.

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

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

The description uses a specific verb ('Check') and resource ('local receipt for a mutation request ID'), making the tool's purpose immediately clear. It is distinct from sibling tools because it is the only one about verifying the status of a previously issued mutation request rather than performing or querying domain operations.

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

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

The description gives clear when-to-use context: check the local receipt before further writes, especially when a request is pending or unknown. It also provides an explicit exclusion—do not automatically create a new ID as a retry—but it does not name alternative sibling tools or state when not to use this tool.

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

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

Beyond the annotations, the description discloses that normal write permissions are required, a current revision and unique request ID are needed, closed items are unsupported, and project children cannot be enumerated before restoration. This adds meaningful non-obvious behavioral context that the schema and annotations do not carry. No contradiction with readOnlyHint=false, destructiveHint=false, or idempotentHint=true.

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 compact and front-loaded with the core behavior in the first sentence. Subsequent sentences each add necessary constraints or ordering prerequisites without redundancy. The phrasing is efficient, and every clause serves a distinct purpose.

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

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

For a state-changing restore operation with a nested target, required revision, request ID, and project-child ordering pitfalls, the description covers the operation, prerequisites, constraints, and restoration-order behavior. The output schema is present, so the description does not need to enumerate return fields. The 'receipt verifies exposed root fields and destination' note adds useful completion context.

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

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

Despite 0% schema description coverage, the description maps the three parameters to real-world meanings: 'current revision' for expectedRevision, 'unique request ID' for requestId, and the target kind distinction between 'open to-do' and 'open project' for the target object. It also implies the destination behavior based on kind. It does not fully describe all validation or edge cases, but it compensates reasonably for the schema gap.

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 first sentence states a specific verb and resource: 'Restore one open to-do to Inbox or one open project to Today from Trash.' This clearly distinguishes the operation from siblings like things_trash_item and things_move_item, whose direction of action is the opposite. The destination nuance for todos versus projects adds precise scope.

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

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

The description gives clear use context: restore only from Trash, only open items, and restore a project before its children. It does not explicitly name alternative tools for different operations, but the exclusion of closed items and the ordering requirement give practical guidance. It would be stronger with an explicit 'use things_move_item for non-Trash moves' note.

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

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

Annotations already declare readOnly=false, destructiveHint=true, and idempotentHint=true; the description adds useful behavioral context by specifying Mac-timezone interpretation, the need for the current revision, and the fact that reminders and repeating rules are not set. No contradiction with annotations exists.

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

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

Three short sentences, front-loaded with the core operation, then preconditions, then behavioral limitations. Every sentence earns its place and there is no redundant or filler content.

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

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

Given the nested target object, rich annotations, and an output schema, the description covers the core operation, prerequisites, timezone, and non-goals. It is sufficient for correct invocation, though explicitly naming an alternative for reminders or repeating rules would make it more complete.

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

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

With 0% schema description coverage, the description compensates by mapping all core parameters to concepts: to-do/project maps to target.kind, current revision to expectedRevision, unique UUID to requestId, and explicit calendar date to date. It adds semantic value beyond the raw schema, though it does not detail every nested field.

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

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

States a specific verb and resource: 'Schedule a to-do or project on an explicit calendar date in the Mac timezone.' This clearly distinguishes the operation from siblings like move/trash, though it does not explicitly contrast it with things_update_item.

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

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

Provides prerequisites ('Requires its current revision and a unique UUID requestId') and a limitation ('Does not set reminders or repeating rules'), so an agent has context for when this is appropriate. However, it does not name an alternative tool or give an explicit when-not-to-use condition for scheduling versus updating.

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

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

The description adds meaningful behavioral context beyond the annotations: it changes only the Mac view, requires writes, and returns a dispatch receipt rather than visible results or task data. This is valuable disclosure of side effects and return semantics, consistent with idempotentHint=true and readOnlyHint=false.

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

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

Three sentences with no fluff. The primary action and key caveat are front-loaded, and the warning about URL dispatch is placed immediately where it matters most.

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

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

The description gives essential behavioral caveats and works well with the schema's enum for view. However, it leaves a notable gap around how query relates to the 'search' view and how requestId should correlate with request status checks, especially given the 0% schema description coverage.

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

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

Schema description coverage is 0%, so the description must compensate. It explains tags ('optionally filtering by tags') and view ('built-in Things view'), but it does not explain the query parameter's role with 'search' or why requestId is required beyond calling it a request ID. Two of four parameters remain under-specified.

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

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

The description names a specific verb ('Open') and resource ('search or a built-in Things view'), with an optional tags filter. It does not explicitly distinguish itself from the sibling things_navigate, but the 'Mac's view only' scoping clarifies that this is a view-changing operation, not a data-retrieval or mutation operation.

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

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

The description implies use when the agent needs to change the Mac's displayed view rather than retrieve data, especially with 'This changes the Mac's view only' and 'receipt confirms URL dispatch, not a visible result or returned task data.' However, it does not explicitly state when to prefer this over siblings like things_navigate, nor does it give exclusions.

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

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

The description discloses important behavioral boundaries beyond the annotations: it moves rather than permanently deletes, includes checklist contents, requires a separate Trash grant, and does not empty the Trash or delete projects/areas/tags. This meaningfully complements the destructiveHint and idempotentHint annotations with concrete side-effect 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 tightly structured: the main action and scope come first, followed by prerequisites and boundary clarifications. Each sentence adds necessary information without repetition or fluff.

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

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

Given the tool's destructive nature, the description adequately covers what the tool does, what it requires, what side effects it has, and what it explicitly does not do. Combined with the output schema and annotations, an agent has enough context to invoke it correctly and safely.

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

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

The input schema has 0% description coverage, so the description must add meaning. It does so by framing expectedRevision as 'the latest revision', requestId as 'a unique request ID', and target as 'one open to-do'. This helps an agent understand the purpose of each parameter beyond the schema types and patterns, though it does not explicitly name the parameters.

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

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

The description states a specific verb ('Move') and resource ('one open to-do') with an explicit destination ('Things Trash on the Mac'), and clarifies scope by including checklist contents and excluding projects, areas, and tags. This clearly differentiates it from sibling operations like restore, update, or permanent delete.

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

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

The description provides actionable usage context: read and review the target first, requires the latest revision, a unique request ID, write permission, and a separate Trash grant. It does not explicitly name alternative sibling tools or state when not to use it, but the prerequisites and safety warning give clear operational guidance.

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

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

Beyond the annotations, the description discloses important update semantics: omitted fields remain unchanged, deadline null clears the deadline, and arbitrary property editing is disallowed. It also emphasizes idempotency through requestId and concurrency control through expectedRevision, which the annotations only hint at.

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

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

Three tight sentences front-load the action and immediately add the most important usage constraints. No filler or repetition exists, and every clause adds value.

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

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

Given the high complexity of the schema, the presence of an output schema, and annotations for read/destructive/idempotent behavior, the description covers the essential semantics needed to call the tool correctly. The main slight gap is not explicitly stating which target kinds support which changes, but the schema's target enum and changes structure mitigate this.

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

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

With 0% schema description coverage, the description compensates well for the critical parameters: requestId must be a unique UUID, expectedRevision must be the latest revision, and changes is a partial object where omitted fields are untouched and deadline null clears it. It does not individually explain every changes subfield, but the schema's names and enums carry some of that weight.

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

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

The description opens with a specific action ('Edit supported fields') and mentions status transitions (complete/cancel/reopen), which clearly distinguishes it from create/trash/move/duplicate siblings. It could be slightly more explicit about area/tag targets, but the core resource and verb are clear.

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

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

The description gives operational guidance such as using the latest expectedRevision and a unique UUID requestId, and it explicitly excludes deletion and arbitrary property editing. However, it does not name sibling tools like trash_item or create_item as alternatives, so when-to-use versus those tools is mostly implied rather than stated.

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