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

The description goes well beyond the annotations by disclosing that a MANUAL award cannot be undone through the API, citing live verification, specific HTTP status codes for unclaim (404) and negative points (400), and the side effect that spend_reward_points inflates spent statistics. This is valuable behavioral context for an irreversible operation.

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

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

The description is compact yet information-dense, using a clear note/warning structure. Every sentence contributes either to the core purpose, the automatic-award caveat, or the critical irreversibility warning. There is minimal redundancy; the final caution reinforces the high-stakes nature without repeating details.

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

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

Given the tool's complexity and the presence of an output schema, the description is complete: it states the trigger conditions, the need to call it separately after mark_done, the irreversible nature of manual awards, the failure modes, and the only compensation path. An agent has enough context to invoke it correctly and avoid harmful manual awards.

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 already documents all three parameters with descriptions and defaults, including 'MANUAL' for item_id. The description adds no meaningful parameter-level semantics beyond reinforcing the manual-award concept, so the baseline of 3 for fully schema-covered parameters is appropriate.

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

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

The description opens with a specific verb and resource: 'Award reward points for a completed task (or a manual celebration).' This clearly defines what the tool does and distinguishes it from reward-related siblings like spend_reward_points, reset_reward_points, and unclaim_reward_points by framing it as the awarding action.

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

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

The description explicitly states when to use the tool: after a task is completed or for a manual celebration, and it instructs to call it separately after mark_done because points are not awarded automatically. It does not exhaustively contrast with all reward siblings, but the manual-award warning and the mention of spend_reward_points as the only compensation give practical routing 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 description is highly transparent: it discloses the undocumented /doc/update endpoint, the Full Access Token requirement, in-place mutation with same _id/createdAt/children, lossless default behavior, and the risk of orphans/cycles. This goes well beyond the annotations and gives the agent crucial operational 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 long but well-structured and front-loaded with the essential conversion semantics. Some verification dates and app-path details could be trimmed without losing actionability, but they support the tool's experimental nature and are not padding.

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 an experimental and potentially risky conversion tool, the description covers prerequisites, side effects, field preservation/clearing behavior, return values, and a critical warning. An output schema exists, so return-value documentation is not required here; the description is operationally complete.

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

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

Schema coverage is 100%, but the description adds meaningful nuance beyond the schema: it explains the default False for clear_project_fields means lossless conversion, clarifies what gets cleared when True, and notes that removed values are returned in removed_project_fields. This is useful supplementary meaning for a documented parameter set.

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 an explicit, specific operation: 'Convert project→category or category→project IN PLACE'. This clearly distinguishes it from sibling create/update tools and explains the core type-changing behavior.

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

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

The description gives strong usage context: it warns not to convert a category with subcategories, tells the agent to check get_children first, and explains when to choose clear_project_fields=True vs the lossless default. However, it does not explicitly contrast itself with update_category_or_project or other siblings, so the alternative-selection guidance is mostly implied.

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 mark it as a non-read-only, non-destructive, non-idempotent mutation; the description goes well beyond that by disclosing endpoint divergence (/doc/create vs /addProject), live-verified field-ignoring behavior, and a client-side local block that prevents the '#word' corruption bug before any API call. Minor gap: it does not spell out permissions/auth for the project path or what the response contains, though an output schema 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?

Front-loaded with the action and the category/project split, then ordered by caveat severity (field rejection → creation-time ignores → title corruption bug). It is long and mildly redundant, since the schema already labels several fields 'Projects ONLY', so parts of the body repeat structured data.

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 15-parameter creation tool with two divergent API backends, the description supplies the cross-parameter rules, the workaround path (update afterwards), and the title validation rule that no other field covers. Annotations and the output schema handle the safety and return-value halves, so nothing material is missing.

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

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

Schema coverage is already 100%, yet the description adds cross-field semantics the schema cannot express: day/due_date/priority/frog are structurally meaningless for categories, label_ids applies to both kinds, and startDate/endDate are silently ignored at creation. These are genuine usage-critical constraints beyond per-parameter text.

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

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

Opens with a specific verb+resource pair and immediately disambiguates the two modes ('Create a category (via /doc/create...) or a project (via /addProject)'), which is exactly the distinction an agent needs given both live behind one tool name. It also states the containment rule (categories can contain categories; projects cannot), separating it from sibling tools like create_task and create_event.

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?

Gives clear conditional routing for the two kinds and explicitly redirects to update_category_or_project for startDate/endDate that cannot be set at creation. It does not, however, state when to prefer this tool over create_task/create_event or note prerequisites such as the Full Access Token requirement beyond the parenthetical mention of it for /doc/create.

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 a non-obvious behavior: event creation is local and external calendar sync only happens if the Marvin client app is running. This adds value beyond the annotations, which are all false and provide no safety profile. The 'EXPERIMENTAL' label further signals risk.

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

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

The description is two sentences. The first sentence delivers the purpose immediately, and the second adds a critical caveat. There is no wasted wording 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?

Given the fully documented schema and the presence of an output schema, the description covers the essential creation context and the important client-sync dependency. It lacks only usage-alternative guidance, which is a usage-guidelines gap rather than a completeness gap.

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

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

Schema coverage is 100% with descriptions for all four parameters, including an ISO 8601 format example for start_iso and an exclusiveMinimum constraint for length_minutes. The description itself adds no extra parameter semantics, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: 'Create a calendar event.' This distinguishes it from sibling tools like create_task, create_time_block, and create_category_or_project. The 'EXPERIMENTAL' prefix does not obscure the core purpose.

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

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

The description gives no guidance on when to use this tool versus alternatives such as create_time_block or create_task. The sync caveat describes a behavioral constraint but does not explain when this tool is appropriate or when a sibling should be chosen instead.

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

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

Annotations only declare the safety profile (write, non-destructive, non-idempotent), while the description discloses far more: X-Auto-Complete: false means titles are stored verbatim and quick-add syntax is NOT parsed, and silently ignored fields (startDate/endDate) are called out with live-verification dates. It also explains the failure mode of the shortcut path (a '#word' stored as parentId makes the task invisible), which is exactly the kind of consequence an agent cannot infer from 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?

Purpose and the key title-parsing rule are front-loaded, which is good, but the middle paragraph on Time/taskTime, reminders, events and time blocking is largely tangential to invoking this tool correctly, and the closing strategy paragraph is dense. For a 19-parameter tool some length is warranted, yet several sentences do not earn their place for a create call.

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 an output schema present the description need not explain return values, and it still covers the gaps structured data cannot: parser behavior, silently ignored fields, storage-vs-UI divergence for strategy fields, and inter-tool handoffs. Nothing an agent needs to call create_task correctly appears to be missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns an extra point by telling the agent which parameters to use in place of quick-add syntax (parent_id, day, priority, time_estimate_minutes, label_ids) and by clarifying that strategy-dependent fields (planned_week/month, review_date, backburner, sections) are persisted even when the strategy is off in the UI.

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?

Opens with a specific verb+resource ('Create a task in Amazing Marvin') and immediately differentiates scope from siblings by naming update_task for start/end dates and by stating that time blocking belongs to time blocks, not this tool. An agent can separate create_task from create_event, create_time_block and update_task without opening a schema.

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

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

Gives concrete routing: set startDate/endDate with update_task after creation, set a clock Time in the app rather than via MCP, and prefer priority/frog parameters over date-based scheduling. It lacks an explicit 'use create_event instead when…' statement, so the event/time-block distinction is only implied.

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

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

Annotations only say the operation is not read-only/no idempotence/no destruction, but the description adds value by revealing that this is an unofficial workaround through /doc/create and that the result must be manually verified. 'EXPERIMENTAL' warns about reliability beyond what the structured annotations provide.

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

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

The description is a single front-loaded sentence that conveys experimental status, the endpoint, auth requirement, and post-call verification without excess wording. Every clause carries useful operational 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 four-parameter experimental write tool, the description covers the essential invocation context: the endpoint, token requirement, risk, and verification step. An output schema exists and param coverage is complete, so return values and parameter details are already handled elsewhere.

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

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

Schema description coverage is 100% and each of the four parameters already has a clear format description (e.g., 'YYYY-MM-DD', 'HH:mm'). The tool description does not need to repeat parameter details and adds no additional semantic meaning beyond the schema.

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

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

The description begins with a specific action and resource: 'Create a time block' and further identifies the exact implementation route via /doc/create. It also flags a critical distinction from sibling tools by noting no official endpoint exists, so an agent can tell it apart from create_task/create_event.

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 clear context for use: the tool is experimental, has no official endpoint, requires a Full Access Token, and should be verified in the app. It does not explicitly name alternatives or say when not to use it, so it stops 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?

Beyond the destructiveHint and idempotentHint annotations, the description discloses an important side effect: for task reminders, only the server-side entry is removed and the task's reminder fields remain, allowing the app to recreate it. This is exactly the kind of behavioral detail an agent needs to avoid incorrect expectations.

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

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

The description is compact and front-loaded: the main action is stated first, then the caveat and usage preference follow. Every sentence adds meaningful information with 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 destructive delete operation, the description covers what is deleted, what is not deleted, when it is safe to use, and where to get the target IDs. Combined with the output schema and annotations, an agent has enough context to invoke it correctly and anticipate side effects.

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

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

The schema already documents reminder_ids as 'IDs of reminders to delete,' so the baseline is 3. The description adds useful semantic guidance by specifying that IDs should be standalone reminders or orphaned entries from get_reminders, which helps the agent select valid inputs rather than task-associated reminders.

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

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

The description opens with a specific verb and resource: 'Delete one or more server-side reminders.' It clearly distinguishes the server-side behavior from task-document reminder fields and references standalone reminders of type 'M', making it easy to tell apart from broader task deletion 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 explicit usage guidance: prefer deleting standalone reminders or cleaning up orphaned entries from get_reminders, and warns against relying on it for task reminders because the app may recreate them. This tells the agent when to use the tool and when the result may be incomplete.

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?

Goes well beyond the destructiveHint annotation: irreversible PERMANENT deletion, trash bypass, stale-client rendering behavior, conflict-resolution recreation risk, required reload procedure, and full-access-token requirement. Adds genuinely valuable operational context not present in structured data.

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?

Severely overlong and meandering: parenthetical asides, a dated live-testing narrative, and an unrecorded-client anecdote bury the critical actionable rules. Front-loading is decent but the volume of incident detail dilutes the core guidance.

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

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

Covers destructive semantics, auth requirements, recovery limits, and post-deletion verification steps; output schema exists so return values needn't be explained. The verbosity is a style issue more than a completeness gap.

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

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

Schema coverage is 100% and there is only one required param (item_id), so the schema fully carries parameter meaning. The description adds no syntax or format detail beyond the schema, warranting the baseline 3.

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

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

States a specific verb+resource (delete a task/document via /doc/delete) and distinguishes itself sharply from in-app deletion by noting the client-side trash bypass. No sibling ambiguity remains.

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?

Explicit when-to-use ('only when the user explicitly wants a deletion'), when-not (recurring task generators, cases where undo matters), and a named preferred alternative (delete in the app for trash/restore behavior).

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

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

Annotations already declare readOnlyHint=true, and the description's 'Get' aligns with a read operation, so there is no contradiction. The description adds modest context by revealing the endpoint and example response fields, but it does not disclose auth requirements, error behavior, or rate-limit implications.

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 with the verb and resource front-loaded, followed by endpoint and example fields. Every part earns its place; 'etc.' is slightly vague but acceptable in this context.

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 tool with an output schema, the description is sufficiently complete. It identifies the resource and key fields, while additional return-structure details are already available from 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 input schema is empty, so there are no parameters to document; the baseline of 4 applies. The description adds some value by hinting at the response contents (email, tracking status), though this is not strictly required for a zero-parameter tool.

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

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

The description states a specific verb ('Get'), a clear resource ('account info'), the endpoint ('/me'), and example fields ('email, tracking status'), making the operation unambiguous. It is naturally distinct from sibling tools like get_rate_limit_status or test_connection.

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

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

No guidance is provided on when to use this tool versus its siblings or when not to use it. The agent must infer intent solely from the name and brief description; no alternatives or exclusions are mentioned.

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

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

The description adds hierarchy-structure behavior beyond the readOnlyHint annotation: it returns the full hierarchy and indicates the root level. This is useful context, though it could have been richer about ordering or response shape.

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

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

Two sentences, front-loaded with the action and scope, followed by the intended use case. Every word earns its place with no repetition or 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?

With no parameters and an output schema present, the description is complete for an agent to understand what the tool returns and when to call it. The hierarchy note and parentId hint cover the key conceptual 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?

Tool has 0 parameters, so the baseline is 4. The description adds helpful meaning about the parentId field and its role in the hierarchy, which helps an agent interpret the response even though there are no 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?

States a specific verb and resource: 'Get all categories and projects', and explicitly clarifies scope as 'the whole hierarchy' with parentId='root' as the top level. This distinguishes it clearly from siblings like get_children, which likely returns a narrower subset.

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 an explicit use case: 'Use to find the right parent_id when creating/moving.' This gives clear context for when the tool is valuable, though it does not mention explicit exclusions or alternative 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?

Beyond the readOnlyHint annotation, the description reveals important behavioral edge cases: direct-children-only traversal, orphan exclusion from 'unassigned,' and the FIX_CYCLES() repair path. This is substantial behavioral context that an agent could not infer from annotations or schema alone. No contradiction with the readOnlyHint 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?

The main behavior is front-loaded in the first sentence, followed by a concise recursion note and then a detailed but relevant orphan edge-case caveat. Each sentence earns its place, and the live-tested date adds credibility without excessive verbosity.

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

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

For a simple one-parameter read-only tool with an output schema, the description fully covers the core operation, iteration strategy, and an important data-consistency quirk. It also supplies a remediation path. Nothing essential is missing for an agent to call this tool correctly and interpret its results.

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 already provides 100% coverage for the single parameter parent_id, including valid special values like 'unassigned' and 'root'. The description repeats the notion of 'category/project' but does not add new parameter-level syntax or format details beyond the schema. Baseline 3 is appropriate because the schema carries the semantic 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 states a specific verb and resource: 'Get open tasks and subprojects in a category/project.' It also clarifies scope by noting 'Returns direct children only,' which distinguishes it from recursive traversal and aligns with the tool's name. This is sufficiently differentiated from sibling tools like get_categories and get_today_items.

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

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

It gives explicit guidance: 'call again for deeper levels' tells the agent how to navigate hierarchies. The orphan note also explains when not to expect orphans and points to get_today_items/get_due_items as alternatives for orphans with a day/dueDate, providing 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.

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

With only readOnlyHint and openWorldHint in annotations, the description goes far beyond by disclosing the undocumented endpoint, filtering on day vs doneAt, future-day caveats, 429/error handling, cache invalidation, excluded items, sorting, and API cost. This is exceptionally transparent behavior documentation.

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 purpose is front-loaded and every sentence carries non-obvious information, but the text is dense and somewhat run-on. Given the undocumented endpoint and multiple edge cases, the length is justified, though it could be tightened.

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 an output schema present and annotations covering the safe-read nature, the description fully covers selection and invocation: parameters, edge cases, failure behavior, cache semantics, exclusions, and cost. Nothing critical is missing for correct use.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning by explaining timezone behavior, that omitting date defaults to today, how lookback_days catches earlier-scheduled tasks, and the per-day cost of each lookback day. This goes beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: "Tasks completed on a given date (doneAt within that day, configured timezone)", clearly distinguishing it from sibling tools like get_today_items and get_due_items. It also clarifies scope with exclusions like "regardless of priority and deadline" and "Tasks only — completed projects are not listed."

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 context for when to use the tool: to retrieve tasks completed on a specific date, with lookback behavior and exclusions. It does not explicitly name alternative tools or state when not to use it, but the scope is precise enough for an agent to select it correctly.

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

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

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds the 'open' status filter and the deadline range behavior, which is helpful, but it does not clarify what 'open' means or any other behavioral details beyond the annotation.

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

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

One compact sentence that front-loads the action and resource, then states the deadline filter. There is no wordiness or redundant 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, optional-parameter read-only tool with an output schema, the description plus annotations and schema fully cover what an agent needs. The main concepts—open items, deadline today or earlier, and optional override—are all represented.

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

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

The single parameter `by` is fully documented in the schema with format and default behavior, so the schema carries the parameter-semantics burden. The description adds no new parameter detail beyond restating the 'today or earlier' concept.

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

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

The description uses a specific verb ('Get') with a clear resource ('open tasks/projects') and a precise filter ('deadline today or earlier'). This meaningfully distinguishes it from the sibling tool get_today_items, which appears to cover only today's items.

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

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

The description implies the tool is for overdue items plus items due today, which gives useful context. However, it does not explicitly say when to prefer this over get_today_items or other listing tools, nor does it mention 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 declare readOnlyHint=true, so the read-only nature is established by structured data. The description adds that the result includes status and check-in data, but does not disclose additional behavioral details such as pagination, rate limits, or whether archived goals are included.

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

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

A single, front-loaded sentence with no redundant wording. Every phrase earns its place by naming the resource, scope, and included data.

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 zero-parameter schema, read-only annotation, and presence of an output schema, the description is sufficiently complete. It tells the agent what the tool does and what data to expect, while the output schema covers return-value details.

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 is empty, so there are no parameters to document; the baseline for zero parameters is 4. The description still adds useful scope by clarifying that the tool returns all goals rather than a filtered subset.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('all goals') plus the included data ('status and check-in data'). This distinguishes it from sibling tools that operate on tasks, habits, or time blocks.

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 'Get all goals' implies this tool should be used when the complete set of goals is needed, and there is no parameter-driven filtering. However, it does not explicitly name alternatives or state when not to use this tool, leaving usage boundaries to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by stating the response contains the full history as 'the source of truth for recordings' and explicitly disclosing the absence of title and settings.

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 core action and resource appear in the first clause, followed by a single valuable caveat about missing fields. There is no wasted wording, and every sentence earns its place.

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

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

Given that the tool has only one parameter, a well-described input schema, read-only annotations, an output schema, and no nested objects, the description provides all necessary context. It explains the response's scope and explicitly points to list_habits for missing metadata, making it complete for correct invocation.

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

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

The schema covers 100% of the single parameter with the description 'Habit ID (from list_habits),' which is already clear. The tool description mentions 'habitId' but does not add format, source, or usage details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the verb 'Get' and the specific resource: the server's tracking record for a single habit, including 'habitId + full history.' It also distinguishes itself from list_habits by noting exactly what the response omits, making the tool's purpose immediately clear to an agent.

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

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

The description provides useful context about when to use this tool versus list_habits, noting that title and settings are not included in this response and 'those are in list_habits.' It gives a clear sense of the available alternatives, though it does not explicitly state 'use this when you need full history' or list exclusion cases.

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 provide readOnlyHint=true, and the description adds useful behavioral context: kudos is separate from reward points and nextMultiplier is absent due to a known limitation. This goes beyond the 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?

The description is three purposeful sentences: it states the action, clarifies a likely currency confusion, and documents a limitation. No filler or repeated schema 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 tool with an output schema, the description covers purpose, sibling differentiation, and a known limitation. 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?

The tool has zero parameters, so the baseline is 4. There is nothing for the description to add about parameter semantics, and the input schema is already complete.

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

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

The description states a specific verb ('Get') and resource ('kudos, level and kudosRemaining') and names Marvin's XP system. It explicitly distinguishes kudos from reward points and points to get_account_info, so the tool's purpose is unambiguous and separable from siblings.

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

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

The description tells the agent that reward points belong to get_account_info, effectively saying 'use this for kudos, not reward currency.' It also flags that nextMultiplier is not available here. It lacks an explicit 'use when...' statement, but the context is clear enough.

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

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

The annotations already declare readOnlyHint=true, so the description does not need to restate that this is a safe read operation. The description adds a use-case hint but no extra behavioral traits such as pagination, rate limits, or auth requirements. This is adequate given the annotation coverage, but no more than that.

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 primary action ('Get all labels') and appends a compact purpose clause. Every word adds value, and there is no redundancy or 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 zero-parameter, read-only tool with an output schema present, the description is complete. It names the resource, indicates the purpose, and relies on the output schema for return-value details. There are no missing prerequisites or hidden configuration requirements to worry about.

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 schema is trivially covered at 100%, so the baseline for parameter semantics is 4. The description contributes nothing about parameters because there are none to document; this is appropriate.

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

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

The description uses a specific verb and resource ('Get all labels') and adds a clear purpose ('for label_ids when creating/filtering'), which distinguishes it from sibling getters like get_categories or get_goals. An agent can immediately tell what this tool returns and why it exists.

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 parenthetical gives clear context for when to use this tool: when you need label IDs for creating or filtering tasks. It does not explicitly name alternative tools or state when not to use it, but the resource being labels is distinct enough among siblings that the context is sufficient.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: the budget is 1440/day and shared by all tools. This helps the agent understand that calls to other tools consume this budget. No contradictions 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?

A single, front-loaded sentence that conveys the purpose and the key constraint. Every word earns its place, with no filler or repetition of annotation data.

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 status tool with an output schema, the description is complete. It explains what is being measured and the relevant budget, which is all an agent needs to select and invoke the tool correctly.

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

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

The tool has zero parameters, so the baseline is 4. There is nothing for the description to add about parameter semantics, and the schema coverage is complete by default.

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

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

The description states a clear verb ('Show') and resource ('how many Marvin API calls have been made today'), making the tool's purpose immediately obvious. It also includes the daily budget context, which distinguishes it from sibling tools like get_account_info or test_connection.

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: this is the tool for checking today's API call usage against the 1440/day budget. It does not explicitly name alternatives or exclusions, but the unique purpose is evident and the shared-budget note helps the agent understand when to consult it.

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

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

The readOnlyHint annotation already establishes this is a read-only operation, and the description adds useful context beyond that: reminders are server-side push notifications and the Full Access Token is required. This extra behavioral context is valuable and does not contradict the annotations.

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

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

The description is two sentences with no filler. It front-loads the core action and resource, then adds the relevant auth requirement. Every sentence earns its place.

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

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

For a zero-parameter, read-only list tool with an output schema, the description covers what an agent needs: the resource type, its scope, and the required token. There are no gaps that would prevent correct invocation.

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

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

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to document, and the description appropriately avoids inventing parameter-level details.

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

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

The description states a specific verb and resource: 'Get all server-side reminders', and clarifies the special meaning of reminders as 'push notifications to the phone'. This is enough to distinguish the tool from its sibling set_reminder and delete_reminder without opening 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 provides no explicit guidance about when to use this tool versus its siblings, nor does it mention when not to use it. It only notes the auth requirement, which is a prerequisite rather than usage context.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to repeat safety. The phrase 'source of truth' adds some behavioral context, but the 'max 100 per call' largely duplicates the schema's 'Up to 100 task IDs' rather than disclosing new behavior.

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

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

A single sentence that front-loads the core purpose and packs the key constraints ('source of truth', 'max 100 per call') without wasted words. Every element 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 read-only tool with one well-documented parameter and an output schema, the description includes the essential constraints. It omits edge-case behavior for exceeding 100 IDs, but that is minor given the overall clarity.

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

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

Schema description coverage is 100%, with the only parameter already documented as 'Up to 100 task IDs'. The description's 'max 100 per call' add no new meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description clearly identifies the operation ('Get time-tracking history') and the resource ('for the given tasks'), and adds the qualifier 'source of truth' to distinguish it from other tracking-related tools. It does not explicitly name or contrast siblings, so it stops short of a 5.

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

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

The description implies usage when you need authoritative time-tracking history for specific tasks, and the 'max 100 per call' constraint gives a practical boundary. However, it provides no explicit guidance on when not to use it or which sibling tool to choose instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds substantial context beyond them: rollover inclusion semantics, timezone resolution order, the caveat that today's recurring tasks may be missing until the client generates them, and an explicit note that clock-time items are untested. This is unusually candid behavioral disclosure.

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

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

The core selection rule and the sibling exclusion are front-loaded, which is correct. The trailing provenance note ('Observed 2026-09-11...') and untested-clock-time remark are useful but slightly verbose, keeping it short of a 5.

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?

An output schema exists, so return values need not be described. Given that, the description covers the selection semantics, the alternative tool, timezone handling, and known staleness caveats — nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single parameter's schema description already states the YYYY-MM-DD format, the day <= date behavior, and the timezone fallback. The description largely restates this, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource (open tasks/projects) plus the exact selection rule (day <= date, including rollover items, not just items on that day). It also distinguishes itself from the sibling get_due_items, which handles deadline-only tasks.

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

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

Explicitly names the alternative for the excluded case ('Tasks that only have a deadline are not included; fetch them with get_due_items'), giving a clear when/when-not routing rule. The default-timezone behavior of omitting the date is also spelled out.

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

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

Annotations already mark the tool as read-only, and the description goes further by disclosing a meaningful API limitation: the response lacks the category link and the mapping is fetched separately from plannerSmartLists. This gives the agent useful expectations about data shape and an extra lookup without contradicting the readOnlyHint.

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

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

Two sentences, with the primary purpose front-loaded and the critical limitation placed immediately after. No filler or redundant restatement of the schema; both sentences earn their place.

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

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

Given the simple surface area, rich schema parameter descriptions, output schema, and read-only annotations, the description covers the important non-obvious behavior. The only notable completeness gap is the lack of explicit sibling comparison, but the core calling context is sufficiently conveyed.

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 parameters are already well documented. The description adds useful implementation context about the category-mapping lookup and normalized block title, but it does not substantively add to the parameter-level meaning beyond what the schema already states.

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

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

The description clearly identifies the operation ('Get') and the resource ('today's time blocks'), so the purpose is immediately understandable. It does not explicitly name a sibling to distinguish itself from, though 'time blocks' is reasonably distinct from tools like get_today_items or get_time_tracks.

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 direct guidance about when to use this tool versus alternatives such as get_today_items, get_time_tracks, or create_time_block. The first sentence implies retrieval of today's blocks, but it never states exclusions or conditions that would route an agent to a different 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?

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds a small but useful behavioral detail with '(if any)', indicating that the result may be empty when no task is being tracked. This is modest extra context beyond the annotations, not a rich behavioral disclosure.

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

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

The description is a single sentence with no wasted words. It front-loads the core action and resource, and the parenthetical '(if any)' adds necessary optionality information 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?

For a zero-parameter, read-only tool with an output schema and readOnlyHint annotation, the description fully satisfies the agent's needs. It clearly states what the tool returns and the optional nature of the result. No additional context about return values is required because an output schema exists.

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 there are no parameter semantics to document. The schema coverage is effectively 100% because the input schema is empty, and the description correctly focuses on output rather than input. The baseline of 4 applies here since no parameter explanation is needed.

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 ('Show') and a precise resource ('which task is currently being time-tracked'), which makes the tool's purpose immediately clear. It also naturally distinguishes it from related siblings like get_time_tracks by emphasizing the current active tracking state rather than a history of tracks.

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 'currently being time-tracked (if any)' clearly signals the intended use case: check the active tracking state. It does not explicitly mention alternatives or exclusions, but the 'current' qualifier is enough context to prevent obvious confusion with time-tracking history 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 mark readOnlyHint=true, but the description adds the Full Access Token requirement, the lazy-registry behavior of the alternative endpoint, and the exact history format (time/value pairs in unix ms). These are behavioral facts beyond the annotations.

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

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

The description is three sentences with no filler: core purpose first, then auth requirement, then an 'Important' caveat with a verification date. Every clause earns its place.

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

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

It covers what the tool returns, the required token, and a non-obvious failure mode. An output schema is present for structured return details, so no essential invocation context 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?

The tool has zero parameters, so there is no parameter detail to clarify. The schema coverage is 100% and the description has nothing to add, which meets the baseline for a parameterless tool.

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

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

The description states a specific verb and resource: 'Get all habits as full documents incl. title, settings and history'. The word 'all' plus the detailed output format clearly distinguishes this from siblings like get_habit and from a non-raw /habits endpoint.

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

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

It explicitly says the non-raw /habits variant 'would be wrong here' and explains why (registry lazily created, missing never-recorded habits, responses lack titles). It also names the required auth variant, so an agent knows when and how to use this tool.

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

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

The description goes far beyond the annotations by disclosing side effects: it stops running time tracking, writes the tracking interval to task.times, records receipts in /tracks, keeps the original pinned task open, creates a new ID for the completed copy, and leaves `day` untouched. It even notes a server behavior change with dates. The idempotentHint=true is consistent with the 400-already-done and deterministic recurring-ID notes, so there is no contradiction.

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

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

The opening sentence is front-loaded and clear, but the rest is a dense wall of parentheticals, semicolons, and date-stamped caveats. Every sentence earns its place, yet the structure could be improved with bullets or separation between error handling, recurring tasks, and side effects. It is appropriately sized for the complexity but not concise in form.

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 mutating tool with one parameter and an output schema, the description is remarkably complete: it covers valid/invalid targets, recurring instances, error semantics, side effects on time tracking, pinned tasks, day-field behavior, and how to read back completed tasks. An agent has everything needed to invoke the tool correctly and anticipate consequences.

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

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

The schema already covers the single item_id at 100% with 'Task ID (NOT a project — see description)'. The description adds extra semantic value by specifying the deterministic recurring instance ID format ('YYYY-MM-DD_<recurringTaskId>') and by reinforcing that projects are invalid; this helps an agent construct the correct parameter value beyond the schema itself.

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

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

The description opens with a specific verb and resource: 'Mark a task as done (via /markDone, with the correct timezone offset)'. It explicitly narrows the scope to tasks only and distinguishes this from projects by citing the live 400 error, so an agent can separate it from sibling tools like unmark_done or update_task without opening schemas.

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

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

It gives explicit when-to-use guidance: tasks ONLY, projects should be completed in the Marvin app, and /doc/update would technically work but skips side effects. It also covers recurring tasks, error-code meanings, and the tracking side effect, which collectively tell an agent exactly when to choose this tool over alternatives.

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

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

The description adds value beyond the annotations by disclosing that the sync database is updated and the Marvin app reflects the change immediately. Since the annotations already establish this is a mutating, non-idempotent operation, this is meaningful extra context rather than redundancy. 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?

Two concise, front-loaded sentences with no filler. The first sentence states the primary action, and the second explains an important behavioral side effect and why it matters.

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 mutation tool with full schema parameter coverage, annotations covering the safety profile, and an output schema present, the description is complete enough for correct invocation. The sync-database side effect is explicitly disclosed, leaving no critical behavioral 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?

All three parameters have complete descriptions in the input schema, so the baseline applies. The description does not add parameter-level detail, and the mention of updateDB=true could be slightly confusing since it is not a schema parameter. Overall, the schema carries the parameter documentation burden adequately.

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 identifies the action ('Record (or undo)') and the resource ('a habit'), making the tool's purpose immediately understandable. It does not explicitly call out sibling tools, so it stops short of full differentiation, but the verb and resource are distinct from task-oriented siblings like mark_done/unmark_done.

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

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

The description implies the tool is for recording or undoing habit entries, but it gives no explicit guidance on when to prefer it over list_habits/get_habit or how it relates to task completion tools. The core use case is inferable, but the description lacks explicit when/when-not guidance.

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

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

The description goes well beyond the annotations by detailing what is destroyed ('whole earn/spend history'), what happens to the balance ('sets the balance to 0'), and that the operation is permanent ('CANNOT be undone'). It also discloses the authentication requirement ('Full Access Token').

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 most important fact ('PERMANENTLY') stated first. Every clause adds value: what happens, auth requirement, irreversibility, and usage condition.

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 parameterless destructive action, the description covers the purpose, the behavioral impact, the irreversibility, the authentication prerequisite, and the appropriate trigger condition. The output schema exists to cover return values, so nothing needed for safe 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?

The tool has zero parameters, and the input schema is empty, so there are no parameter semantics to clarify. The description appropriately focuses on the operation rather than parameters, meeting the baseline for a parameterless tool.

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 ('reset'), a clear resource ('reward points'), and the exact effect: deleting the entire earn/spend history and setting the balance to 0. It is plainly distinguishable from the sibling reward tools (claim, unclaim, spend) because it describes a full reset rather than a point adjustment.

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

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

The description explicitly says to use this only when the user explicitly asks for it, which serves as a strong when-to-use and when-not-to-use gate. The irreversibility warning reinforces the caution needed before invoking this destructive operation.

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, it discloses the Full Access Token requirement, verified isStarred value semantics, the conditional display behavior of low priority while still storing the value, and the server's 500-instead-of-404 error quirk. These are concrete behavioral traits that an agent cannot infer from annotations or 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 dense but every sentence serves a purpose: core function, auth requirement, value semantics, display caveat, project exclusion, and error behavior. Front-loading the purpose and scoping before caveats makes it easy to parse.

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 complexity of the priority/frog semantics, project differences, and server error oddity, the description covers everything needed to call the tool correctly. An output schema exists for return values, so return-format details are not required here.

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

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

Schema description coverage is 100% with detailed value mappings for both priority and frog, so the description does not need to add parameter-level detail. It adds some verification/context beyond the schema but does not significantly extend the meaning of the parameters themselves.

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?

Opens with a specific verb and resource: 'Set or change priority (isStarred) and/or the frog marker on an existing TASK.' It scopes itself to tasks and explicitly disambiguates from projects, which use a different field and sibling tool. This clearly distinguishes it from update_task and update_category_or_project.

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

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

The description states when the tool applies and when it does not: it applies to TASK priority/frog changes, and it explicitly says 'Does not apply to projects' with the alternative 'set it via update_category_or_project.' It also gives a behavioral cue for invalid IDs (permanent 500) and advises fetching a fresh ID, so an agent knows not to use this tool with stale IDs.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses that a Marvin reminder is normally TWO writes, that this tool performs only the server-side /reminder/set write, and that using a task ID risks an orphaned entry 'only visible through get_reminders'. The app-login prerequisite and the practical limitation about taskTime/autoSnooze are also surfaced. No annotation contradiction.

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

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

Front-loads the WARNING and the standalone-only rule before the explanatory detail, which is the right ordering. The trailing 'Facts about time on tasks' paragraph is somewhat tangential to invoking this tool, though it does justify the stated MCP limitation; the definition is long but most sentences earn their 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 write tool with real data-integrity hazards, a 3-param schema at 100% coverage, an output schema, and partial annotation coverage, the description supplies the missing pieces: integrity semantics, prerequisites, safe-use boundary, and the task-reminder limitation. An agent can call this correctly and know when not to.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds reason-level meaning for reminder_id (why a task ID is dangerous) and clarifies what the reminder represents. It stops short of stating any format details beyond the schema, but the added semantic context for the risky parameter is real 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 first clause states a specific verb+resource ('Set a standalone push reminder') and immediately scopes it as type 'M' requiring the mobile app. It explicitly distinguishes this from task-linked reminders, which is the exact confusion an agent would otherwise have.

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?

Gives an explicit when-to-use ('use this tool for standalone reminders only') and a when-not-to-use ('Task-linked reminders are set in the Marvin app'), plus a concrete parameter-level exclusion ('Setting reminder_id to a task ID therefore does NOT link the reminder'). Alternative routing is 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?

It reveals a non-obvious, live-verified API behavior: the endpoint returns 500 if the balance would go negative. This goes well beyond the annotations, which only list generic hints, and it gives the agent a concrete way to avoid failure.

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 focused sentences: the first names the operation, the second delivers a verified caveat and mitigation. No filler 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?

Given a simple 2-parameter schema, full schema descriptions, and an output schema, the description covers the main action and the critical precondition. It is slightly incomplete only in that it does not clarify what 'a reward' refers to or whether any reward state must exist before spending.

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

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

Schema coverage is 100%, so the schema already documents both parameters (points and date) adequately. The description does not add parameter-level detail beyond the schema; the balance warning relates to the overall operation, not a specific parameter's format.

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

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

The description uses a specific verb and resource — 'spend reward points on a reward' — so it clearly states what the tool does. It does not explicitly compare against sibling tools like claim_reward_points or reset_reward_points, so it falls just short of full differentiation.

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

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

The note gives actionable guidance: check the balance (get_account_info) before large purchases to avoid a 500 error. It does not explicitly say when not to use this tool or name an alternative, but it provides clear situational context.

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

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

Annotations already indicate this is a mutating, idempotent, non-destructive operation, and the description adds little beyond the word 'start'. It does not explain what state changes occur, whether starting tracking again after an active session is handled, or any other behavioral details that would supplement the annotations.

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

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

The description is one short declarative sentence with no filler, and the main verb and object are front-loaded. For such a simple tool, this level of brevity is appropriate and effective.

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

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

With only one required parameter, full schema coverage, and an output schema present, the description provides enough information to make a basic correct invocation. It could explain more about tracking semantics or when to choose this tool, but those are minor gaps given the tool's simplicity.

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

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

The single parameter task_id is fully documented in the schema (100% coverage), so the description does not need to repeat its meaning. The description adds nothing beyond the schema's existing 'Task ID' documentation, making the baseline score of 3 appropriate.

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

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

The description names a specific action ('Start') and resource ('time tracking for a task'), so the core purpose is immediately clear. It does not explicitly contrast with sibling tools like create_time_block or stop_tracking, but the opposition with stop_tracking is strongly implied by naming.

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 explicit guidance on when to use this tool versus siblings such as create_time_block or get_time_tracks. The description simply states what it does, leaving the agent to infer the appropriate context without conditions, prerequisites, or exclusions.

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

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

The description discloses a documented and live-confirmed API limitation: the task's own times/duration fields are not updated by /track STOP. It also names the exception with mark_done and points to get_time_tracks. This adds substantial behavioral context beyond the annotations, which only declare idempotency and non-destructiveness.

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 front-loaded with the primary action and then adds a clearly marked, high-value limitation note. Every sentence earns its place, and the caveat is structured to be easily parsed by an agent.

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

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

For a single-parameter tool with an output schema and non-destructive/idempotent annotations, the description covers the essential behavioral caveats and exceptions. Nothing critical is missing for correct invocation or interpretation.

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

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

The schema already provides 100% coverage with a single task_id parameter described as 'Task ID'. The description does not add new parameter-level detail, which is acceptable given the schema's completeness. Baseline 3 is appropriate here.

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

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

The description states a specific verb and resource: 'Stop time tracking for a task.' It clearly differentiates from sibling start_tracking and explains the precise scope of the action. The additional caveats reinforce rather than obscure the core purpose.

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

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

The description gives clear context about what happens when stopping tracking and where the data lands (get_time_tracks). It also points to mark_done as an exception that writes task.times, which implies an alternative when task field updates are needed. It does not state the when-not condition quite as explicitly as a full 5 would require.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, establishing this is a safe, read-only operation. The description adds the valuable behavioral detail that the tool returns OK only if the apiToken is valid, giving the agent expectation about success criteria without over-specifying.

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, front-loaded with the action and resource, followed by the result condition. Every word earns its place. No filler or redundant restatement.

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, output-schema-equipped tool, this description is fully sufficient. It states the purpose, the success indicator, and is complemented by the annotations. Nothing else is needed for an agent to select and call it correctly.

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

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

There are zero parameters, so the schema trivially covers 100%. The description does not need to elaborate on parameters. The baseline for zero-parameter tools is 4 because no parameter ambiguity exists.

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

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

The description uses a specific verb and resource: 'Test authentication against Marvin's API.' It clearly states what the tool does and distinguishes it from the sibling tools, none of which are connection/auth checks. The success condition ('Returns OK if the apiToken works') further clarifies the behavior.

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

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

The description clearly communicates when to use this tool: when you need to verify authentication or API token validity. It does not explicitly exclude alternatives, but no sibling tool exists for this purpose, so the context is sufficient.

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 cover safety and idempotency, and the description adds valuable behavioral context: MANUAL awards have no server entry, /unclaimRewardPoints returns 404 'No such entry', and the compensation path via spend_reward_points. It does not discuss effects on balances or repeated calls, but annotations cover idempotency and non-destructiveness.

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, starts with the core purpose and examples, then layers edge-case behavior and the alternative tool. Every sentence earns its place with no redundancy 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 output schema, 100%-covered input schema, and annotations, the description is complete enough. It covers what the tool does, when to use it, the critical unsupported case, and the fallback path, leaving no meaningful invocation gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that item_id must reference a real task award and that 'MANUAL' is unsupported with a concrete compensation alternative. This helps the agent understand the parameter's semantic constraint more deeply.

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

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

The description states a specific action ('Undo a point award'), names the resource, and gives concrete examples (misclick, task un-completed with unmark_done). It also distinguishes this tool from spend_reward_points by explicitly assigning manual awards to 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?

Usage guidance is explicit: use this only for awards tied to a real task ID, and use spend_reward_points instead for MANUAL awards. This clearly separates when to call this tool versus the alternative.

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

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

Beyond the annotations, the description reveals that kudos are not adjusted, that reward points can be undone separately, that a permanent 500 means the document does not exist (server behavior verified live), and that it works for generated instances of recurring tasks. This is rich behavioral disclosure that annotations alone do not provide. It also mentions the required Full Access Token, which is important for invocation. 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?

Three sentences, each carrying distinct value: the core effect, the auth requirement plus recurrence behavior, and the notable server error semantics. The content is front-loaded and every sentence earns its place with 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 one-parameter mutation tool with an output schema, the description covers the effect, the auth token, edge cases (recurring tasks), side effects (kudos), and an error behavior that could otherwise cause an agent to think the call failed due to a server fault. Nothing important is missing.

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

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

Schema coverage is 100%: item_id is described as 'Task ID' in the schema itself. The description adds no further parameter-level meaning beyond what the schema already says, which meets the baseline for full 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?

States a specific action (undo a completion), the concrete effect (sets done=false and clears doneAt), and the underlying mechanism (/doc/update). This clearly distinguishes it from mark_done and unclaim_reward_points, and an agent can tell exactly what the tool does without opening the schema.

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

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

The description explains when to use it (after a task has been completed) and explicitly mentions an alternative for undoing reward points (unclaim_reward_points). It doesn't explicitly say 'use this instead of mark_done when...' but the context is clear enough because it names the related sibling and notes what it does NOT adjust.

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?

Goes well beyond annotations (readOnly=false, idempotent=true, destructive=false) by disclosing a hidden cost (1 extra API call when blocked fields are supplied), refusal semantics, a hard prohibition on completing projects due to skipped side effects, transient vs permanent 500 behavior, and that the server returns 500 instead of 404 for missing IDs.

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?

Long but front-loaded: the core verb, resource, scope, and sibling routing come first, and later sentences carry distinct error-handling and field-scoping facts. Dense rather than padded, though some parenthetical provenance dates could be trimmed.

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 21-parameter mutation tool with an output schema already present, the description covers the remaining agent-relevant unknowns: cross-type field applicability, refusal conditions, retry semantics, and the wrong-ID error shape. Nothing needed to invoke it correctly is missing.

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

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

Although schema coverage is 100%, the description adds meaning the schema lacks: the structural rationale for 'Projects ONLY' blocking, confirmation that label_ids applies to both types, that icon is categories-only, and that strategy-dependent fields can be set even when the strategy is disabled.

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 ('Update fields on an existing CATEGORY or PROJECT via /doc/update') and immediately distinguishes itself from the sibling update_task for tasks. An agent can route between update_category_or_project, update_task, and create_category_or_project without opening schemas.

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

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

Explicit when-to-use routing ('For tasks, use update_task') plus explicit when-not guidance: 'Do not complete projects here' and the refusal behavior for category-blocked fields. Also names recovery alternatives (get_categories/get_children) for the missing-ID case.

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

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

Annotations only declare write/idempotent/non-destructive; the description adds far more: Full Access Token requirement, transient 500s being atomic with safe retry, permanent 500 meaning a missing document (server returns 500 not 404), strategy-dependent fields persisting while hidden in the UI, and the MCP-side limitation on clock times/reminders. These are exactly the operational facts an agent cannot get from structured fields.

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?

Front-loaded with purpose and sibling routing, and nearly every sentence earns its place with non-obvious operational detail. It is long, however, and the repeated 'verified in the app 2026-08-29' provenance tag appears ten-plus times and the planned_week sentence sprawls, adding noise to an otherwise tight structure.

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 23-parameter mutation tool with an output schema and annotations, the description covers the remaining agent-facing gaps: auth scope, error/retry semantics, missing-ID recovery via get_categories/get_children, recurring-task restrictions, and client-reload caveats. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100% so the per-parameter docs carry most of the load, but the description adds cross-cutting semantics the schema can't: strategy-dependent fields (start/end date, planned_week/month, review_date, backburner, orbit, sections) are settable even when the strategy is disabled, and the backburner/start_date interaction in the schema aligns with the description's note that scheduling trumps the flag. Useful, though not comprehensive beyond what the schema already states.

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

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

Opens with a specific verb+resource+endpoint: 'Update fields on an existing TASK via /doc/update'. It immediately distinguishes itself from siblings by naming update_category_or_project, set_priority, and mark_done and stating what those handle instead. An agent can route correctly without opening any schema.

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

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

Explicit when/not and alternatives: categories/projects go to update_category_or_project, priority to set_priority, completion to mark_done ('never here'). It also carves out recurring-task recurrence editing as forbidden and restricts simple field edits to single instances, which is a real usage boundary.

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