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

Annotations only provide generic flags; the description adds crucial behavioral detail: manual awards cannot be undone through the API, unclaim returns 404, negative points are rejected with 400, and compensating via spend_reward_points inflates spent statistics. This is meaningful context beyond what annotations or schema 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 dense and front-loads purpose before caveats. The issue reference and verification date add credibility, though they make the description slightly more verbose than strictly necessary.

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?

Together with the full schema and output schema, the description covers the key decision points: when to call this tool, what happens after mark_done, and the irreversible nature of manual awards. No critical invocation detail 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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description reinforces the significance of item_id='MANUAL' and positive point values but does not introduce new parameter-level details 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?

States a specific verb ('Award') and resource ('reward points for a completed task or manually'). It clearly distinguishes itself from siblings like spend_reward_points and unclaim_reward_points by scoping what this tool does.

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

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

Explicitly explains when to call this tool: after mark_done, because mark_done does not automatically award reward points. It also warns that manual awards are irreversible and names the only compensation path, spend_reward_points, giving clear context for choosing 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?

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description goes well beyond these: it discloses that the tool relies on undocumented server behavior via /doc/update, that conversion is a pure type change preserving _id/createdAt/children, that project fields may remain on categories as intentional round-trip data, and that clear_project_fields=True clears specific fields and returns them in removed_project_fields. It also flags the risk of orphans/cycles. This is rich behavioral context that annotations alone do not provide, and it does not contradict them.

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

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

The description is dense but every sentence earns its place: purpose, experimental risk, lossless semantics, the clean-category option, app-path context, and a critical safety warning. It is front-loaded with the core purpose and the most important caveat (EXPERIMENTAL). It is longer than average, but the complexity of the tool justifies the length; minor redundancy exists around the app's correct path being mentioned twice.

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, the 100% schema coverage, and the presence of an output schema, the description is complete. It covers the conversion direction, the undocumented endpoint risk, the lossless behavior, the clean-category alternative, the subcategory safety constraint, and the verification date. An agent has everything needed to decide whether and how to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the lossless default behavior, what clear_project_fields=True actually clears (day/dueDate/priority/isFrogged/firstScheduled), the relationship to the app's buggy Edit Settings path, and the return of removed_project_fields. It also clarifies that item_id comes from get_categories. This elevates the parameter guidance above the baseline.

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: 'Convert a project to a category or back, in place and losslessly.' It clearly distinguishes the tool's bidirectional conversion behavior and immediately contrasts with the sibling update_category_or_project by explaining the type-change semantics. The experimental caveat and lossless-by-default detail further sharpen what this tool uniquely does.

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 when-to-use guidance: use for in-place type conversion, and explicitly warns 'Do NOT convert a category that contains subcategories into a project' with a reason (orphans/cycles) and a check to perform first (get_children). It also explains when to set clear_project_fields=True versus the default lossless path, and notes the app's correct path is not in the menu by default. This is thorough routing and exclusion 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 far beyond the sparse annotations by disclosing real behavioral traits: endpoint routing, Full Access Token requirement, the fact that /addProject ignores certain fields, and a critical corruption bug when project titles contain '#word'. It also notes that the client blocks the bug locally before any API call, which materially changes how an agent should behave. This is exceptional transparency for a mutation tool.

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

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

The description is long and detailed, but nearly every sentence carries operational necessity for a high-risk create operation. It front-loads the core purpose and then organizes caveats by topic, ending with a clearly separated corruption-bug note. It is dense rather than bloated, and the detail is justified by the number of supported fields and edge cases.

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 15 parameters, only 2 required, a complex category-vs-project split, and minimal annotations, this description is remarkably complete. It covers auth requirements, field applicability, sibling-tool routing, unsupported fields, and a serious title-validation bug. With an output schema present, there is no need for the description to explain return values.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real cross-parameter meaning: label_ids applies to both categories and projects, day/due_date/priority/frog are accepted by the API but meaningless for categories, and startDate/endDate are not settable at creation. These insights strengthen the interpretation of the schema without repeating it verbatim.

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: 'Create a category or project with color, icon, labels and note.' It also names the underlying endpoints (/doc/create and /addProject) and clarifies the nesting rule that distinguishes categories from projects. This is immediately distinguishable from sibling tools like update_category_or_project and create_task.

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 guidance about when not to use this tool: startDate/endDate cannot be set at creation and should be handled with update_category_or_project afterwards, and project color must be set via update_category_or_project. It also explains why fields like day/due_date/priority/frog are not meaningful for categories. It does not explicitly contrast with create_task, but the dual resource name makes that boundary reasonably clear.

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

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

Annotations already indicate this is a mutating, non-idempotent operation, but the description adds meaningful context beyond those flags: the feature is experimental, sync is client-side, and the event will not sync onward unless the Marvin app is running. This is useful behavioral information that annotations cannot convey.

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 text is short and front-loads the experimental warning, but it repeats the same information: 'Create a calendar event (experimental)' is immediately followed by 'EXPERIMENTAL: Create a calendar event.' The redundancy prevents it from being as tight and efficient as it could be.

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 complete parameter documentation and an output schema available, the description covers the one critical piece of context that could surprise an agent: the dependency on a running client app for external calendar sync. It does not mention alternative behavior or failure modes, but the structured data covers the remaining essentials.

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 each parameter already has an explicit description, including an ISO 8601 example for start_iso and minimum constraints for length_minutes. The tool description adds no extra parameter-level detail, 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 states a direct action ('Create') on a defined resource ('calendar event') and marks it as 'experimental.' It clearly distinguishes this from sibling tools like create_task and create_time_block by specifying the calendar-event context and external-calendar sync. No ambiguity remains about what the tool does.

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 a clear operational prerequisite: the Marvin app must be running on some device for the event to sync to an external calendar. However, it does not compare this tool with siblings such as create_time_block, nor does it state when to prefer or avoid this tool. Usage is mostly implied by the resource name and purpose.

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 readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, which is minimal. The description carries the full burden and does so richly: it discloses that shortcut parsing is disabled (X-Auto-Complete: false), that startDate/endDate are ignored by /addTask, that clock time must be set in the app, that strategy-dependent fields are stored even when disabled, and that parent_id is not validated (orphan risk). This is exactly the kind of behavioral context an agent needs.

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 every sentence earns its place: the quick-add warning, the startDate/endDate limitation, the clock-time explanation, and the strategy-field note are all non-obvious facts that prevent real errors. It is front-loaded with the core purpose and the most important caveat (shortcut parsing disabled) before the deeper notes. Slightly dense, but justified for a 19-parameter tool.

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

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

For a 19-parameter creation tool with no meaningful annotations, the description covers the critical gaps: what the server ignores, what the app requires, what is stored but hidden, and what can corrupt data. The output schema exists, so return values need no explanation. The only minor omission is pagination or rate-limit behavior, but that is not essential for a single create call.

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, but the description adds meaningful cross-parameter guidance: it tells the agent to use parent_id, day, priority, time_estimate_minutes, label_ids instead of quick-add syntax, and it explains the relationship between backburner and day (scheduling trumps the flag). It also warns against combining is_reward with reward_points. This goes beyond the schema's per-parameter 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 ('Create a task') and immediately enumerates the key fields (category, day, priority, labels, estimate, sections), which distinguishes it from sibling tools like update_task, create_event, and create_category_or_project. It also clarifies what the tool is NOT for (startDate/endDate, clock time), which sharpens the boundary further.

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 when-to-use guidance: prefer priority/frog over dates where possible, use parameters instead of quick-add syntax, and set startDate/endDate with update_task after creation. It also names the alternative tool (update_task) and explains the MCP limitation around clock times, so an agent knows exactly when to route elsewhere.

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 establish that this is a non-read, non-idempotent, non-destructive operation. The description goes far beyond that: it discloses the internal mechanism (/doc/create with db='PlannerItems'), the Full Access Token requirement, the client-side id quirk caused by /doc/create not echoing the server id, and live-test evidence (accepted, listed in /todayTimeBlocks, renders correctly). This is exactly the kind of hidden behavioral context an agent needs.

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 in the first sentence, and the experimental caveat appears immediately after. The trailing verification details are thorough but somewhat verbose, repeating the date twice and including minor specifics (app 1.70.0.0, PWA + desktop) that could be trimmed without losing the trust-calibration value.

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

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

For a tool that is a workaround with no official endpoint, the description is unusually complete: it explains the mechanism, auth requirement, id-handling behavior, downstream usage in task creation, and verification steps. Combined with the existing output schema and full param schema, nothing an agent needs to call 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 description coverage is 100%, with all four parameters (title, date, start_time, duration_minutes) already documented with formats and examples. The description adds no per-parameter detail beyond the schema, which is acceptable since the schema carries the burden. Baseline 3 is appropriate.

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

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

The first sentence states a specific verb and resource: 'Create a time block (experimental) and get its id back.' It distinguishes this creation tool from its sibling get_today_time_blocks by making the outcome (returning the id) explicit, and frames how the id feeds into create_task/update_task, locating it in the tool family without ambiguity.

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 workflow context: the returned time_block_id can be used directly as time_block_section in create_task/update_task, avoiding an extra get_today_time_blocks call. It also warns that the endpoint is experimental and that the agent should verify the block in the app. It stops short of explicitly naming alternatives or stating when not to use it, so it misses the top score.

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 this as destructive and idempotent, but the description adds critical non-obvious behavior: for task-owned reminders, only the server-side entry is removed and the task document's reminder fields remain, so the app may recreate it. This goes well beyond the annotations and clarifies exactly what is and isn't destroyed.

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 efficient sentences: the main action is front-loaded, and the essential caveat follows immediately. Every sentence earns its place with no wasted words.

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

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

For a single-parameter delete tool with an output schema and annotations covering destructiveness and idempotency, the description is fully complete. It covers the main use case, the edge case with task reminders, and how orphaned entries relate to get_reminders.

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 meaningful context about which reminder IDs are valid targets (standalone 'M' reminders versus task-linked reminders), though it doesn't add format or syntax details 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?

States a specific verb and resource: 'Delete one or more server-side reminders.' It also distinguishes itself from sibling tools like set_reminder and get_reminders by clarifying the scope (server-side entries) and target type (standalone 'M' reminders).

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

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

Explicitly instructs when to use the tool: prefer against standalone reminders (type 'M') or orphaned entries from get_reminders. It also warns against relying on it for task-linked reminders, since the app may recreate them—giving clear selection criteria and 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 flag destructive and non-read-only behavior, but the description adds substantial behavioral context beyond them: API deletion bypasses client-side trash, open clients do not reflect the deletion, stale rows can be recreated by the app, and server-side verification via get_children plus client reload is required. This is far more than the 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 long and highly detailed, but the length is largely justified by the destructive, irreversible nature of the operation and the complex client-sync risks. Key warnings are front-loaded in the first lines, though some later evidence-like details (e.g., exact _rev timestamps, 'reported upstream') could be trimmed without losing essential 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?

The description covers authentication token requirements, when not to use the tool, post-deletion verification steps, client reload instructions, and risks of stale client state. Given the destructive and irreversible nature, it is exceptionally complete for an agent to invoke safely and 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 input schema already fully describes item_id as 'ID of the document to delete' with 100% coverage. The description reinforces that the item is a task/document but does not add any new parameter-specific semantics beyond what the schema provides, 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?

The description clearly states the specific operation: permanently deleting a task/document via the /doc/delete endpoint, with explicit emphasis on no trash and no undo. It also distinguishes this from in-app deletion, which sends items to trash, and from removing a recurring task's generator document, which should be handled in the app.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: use only when the user explicitly wants deletion, prefer in-app deletion when undo matters or the app is open, and never use for recurring task generator documents. It names concrete alternatives and the conditions for choosing them.

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 the endpoint and return fields but provides little additional behavioral context such as authentication requirements or any caveats about tracking status. It is non-contradictory and adequate, but not rich.

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 communicates the essential purpose, endpoint, and returned fields with no wasted words. It is concise without sacrificing clarity.

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 read-only endpoint with an output schema and annotations already present, the description is complete. An agent has enough information to select and invoke the tool correctly, and 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 tool has zero parameters, so the description has no parameter semantics to explain. Per the baseline for parameterless tools, a 4 is appropriate; the description adds useful detail about what data the response contains, which is helpful context beyond the empty 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 names a clear verb+resource ('Get account info'), identifies the exact endpoint (/me), and enumerates the specific payload fields (email, tracking status, points balance). This makes the tool's purpose unambiguous and distinguishes it from the many sibling tools.

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

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

The usage context is implied by the resource and fields, but the description does not explicitly state when to prefer this tool over alternatives, nor does it mention any exclusions. No alternative tool serves the same purpose, so the lack is not severe, but no direct usage guidance is provided.

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 this as read-only, and the description adds useful behavioral context: it returns the entire hierarchy, uses parentId='root' for the top level, and is meant for locating parent IDs. This goes beyond the annotations without contradicting them.

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

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

The description is somewhat repetitive: 'Get all categories and projects' appears twice in nearly identical form. It could be condensed into one clear sentence plus the usage note. Still, the key information is front-loaded and the usage hint adds value.

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

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

For a zero-parameter, read-only tool with an output schema present, the description is complete. It explains the hierarchy, the root convention, and the intended use, so an agent has enough to call it correctly and interpret the result.

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. The description does not need to explain parameter semantics and correctly focuses on the return structure and usage purpose.

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 resource (all categories and projects) and the operation (get as hierarchy with id and parentId). It is unambiguous and distinct from sibling tools like get_children or get_labels, though it does not explicitly name alternatives.

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

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

The description explicitly states a concrete use case: 'Use to find the right parent_id when creating/moving.' It gives clear context for when to call the tool, though it does not specify when not to use it or mention 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?

Beyond the readOnlyHint annotation, the description discloses detailed behavior: direct-children-only semantics, orphan exclusion under 'unassigned', and the FIX_CYCLES() repair path. This adds valuable context not available in annotations alone.

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 somewhat lengthy due to the orphan note and live-tested date, but every sentence adds necessary operational detail. It is front-loaded with the main purpose and then expands on limitations, making it well-structured though not maximally concise.

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

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

For a single-parameter read tool with an output schema, the description fully covers behavior, limitations, and troubleshooting. An agent is equipped to call it correctly without ambiguity.

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 complete parameter documentation (100% coverage) including valid values like 'unassigned' and 'root'. The description does not add new meaning to the parameter beyond what the schema states, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves open tasks and subprojects within a specific category or project, using a specific verb and resource. It also distinguishes itself by noting it returns direct children only, and mentions the orphan caveat, which sets it apart from sibling tools like 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?

Explicit guidance is given: call again for deeper levels, and for orphans, use get_today_items/get_due_items instead. This directly tells an agent when to use this tool and when to use 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?

This description goes far beyond the basic readOnly hint, disclosing that it relies on an undocumented endpoint that may disappear, that lookback is needed due to day vs. doneAt filtering, that results are cached for 30 minutes, and that incomplete results are flagged with covers_from and days_missing. It also explains cache interactions with mark_done, delete_task, and unmark_done, plus performance costs. There is 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?

The description is long but each sentence adds critical operational detail. Minor redundancy exists in the opening two sentences both stating the 'completed on a given date' conceptaine, but overall the structure is logical: core purpose, endpoint caveat, caching behavior, exclusions, and cost.

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, the description is exceptionally complete. It covers source endpoint risk, date filtering semantics, caching, error handling with incomplete flags, excluded cases, sorting, and cost estimation. The presence of an output schema further reduces the need to explain return values, and the description covers everything an agent needs to invoke it safely.

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

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

Although the schema already documents both parameters, the description adds substantial meaning: it explains why lookback_days exists, that each day corresponds to one read call (~3.1s), and clarifies timezone interpretation. This elevates the semantics well beyond the bare 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: 'Get tasks completed on a given date', which clearly identifies the tool's function. It further distinguishes itself with details like 'regardless of priority and deadline' and coverage disclaimers ('Tasks only — completed projects are not listed'), making it distinct from sibling list tools such as get_today_items and get_due_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 provides strong contextual guidance on what the tool covers and its limitations, but it never explicitly names alternative sibling tools or states conditions for choosing this tool over them. The 'Not covered' section implies exclusions, but the absence of direct alternative routing keeps this at a minimum viable level.

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 safety profile is covered. The description adds useful selection semantics (open items, deadline today or earlier), but it does not disclose additional behavioral traits such as ordering, pagination, or authentication requirements. No contradiction with annotations exists.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to the meaning, and the core operation, resource, and constraint are immediately clear.

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

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

For a read-only tool with one optional parameter, an output schema, and full schema description coverage, the description is complete enough. An agent can determine what to call, what the parameter means, and what to expect in terms of safety without needing additional context.

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

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

Schema description coverage is 100%: the single optional 'by' parameter is fully documented as an inclusive YYYY-MM-DD deadline, with omission meaning today. The description essentially restates this deadline concept without adding new parameter semantics 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?

Description uses a specific verb ('Get') and resource ('open tasks and projects') with a precise deadline condition ('today or earlier'). It clearly conveys what the tool returns, though it does not explicitly differentiate itself from the similarly named sibling 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?

The intended usage is implied by the description: retrieve tasks/projects that are open and due by today or an earlier date. However, it provides no explicit when-to-use guidance, exclusions, or mention of alternatives such as get_today_items or get_done_items.

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 the description adds meaningful context: the response is the 'source of truth for recordings' and omits title/settings. This helps the agent set expectations beyond the schema without contradicting the read-only hint.

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 no filler: the core purpose comes first, followed by the key limitation and pointer to the sibling tool. Every line 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 single-parameter, read-only tool with an output schema and one relevant sibling, this description is complete. It names the source parameter, clarifies the record scope, and warns about missing fields, covering everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100% and the single parameter habit_id is already described as 'Habit ID (from list_habits)'. The description adds little beyond the schema, mentioning habitId but no new format or constraints, so a baseline 3 is appropriate.

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

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

The description uses a specific verb and resource ('Get a habit's server tracking record with its full history') and explicitly differentiates it from list_habits by noting the response lacks title and settings. An agent can confidently identify this as the single-habit full-history retrieval tool among siblings.

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

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

It clearly states this is for a single habit and points to list_habits as the source for title/settings, giving useful routing context. It does not explicitly enumerate when not to use it, but the alternative is named and the scope 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?

Annotations declare readOnlyHint=true and openWorldHint=false, so the read-only nature is already known. The description adds value by clarifying that kudos is not the same as reward points and by disclosing the known limitation that nextMultiplier is not present in this endpoint (referencing a specific issue). This provides behavioral context beyond what annotations convey, though it doesn't elaborate on return format (covered by output schema) or other side effects.

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 long and front-loaded with the core purpose. The first sentence states exactly what the tool does; the second clarifies a critical distinction and a limitation. Every word earns its place, with no redundancy or 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?

Given the tool's simplicity (no parameters, read-only, output schema present), the description covers all essential aspects: what it returns, how it differs from related tools, and a known limitation. An agent can correctly decide to call this tool and interpret its result without needing additional information.

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 schema is trivially fully documented. The description goes beyond the schema by enumerating the returned fields (kudos, level, kudosRemaining) and explicitly noting that nextMultiplier is absent. This adds semantic clarity for an agent, even though no parameters exist to describe.

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

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

The description clearly states it retrieves kudos, level, and kudosRemaining from Marvin's XP system. It explicitly distinguishes kudos from reward points and points to get_account_info for the point balance, making the tool's purpose unambiguous and differentiating it from sibling tools.

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

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

The description provides clear context: kudos is separate from reward points, and the point balance is found in get_account_info. This implicitly tells the agent when to use this tool (when kudos data is needed) versus get_account_info (for points). It also notes that nextMultiplier is not available here, which is a usage caveat. However, it does not explicitly name the alternative tool or state a definitive when-to-use/when-not-to-use rule, so it falls short of a perfect score.

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 known. The description adds that it returns 'all' labels, implying full coverage, but does not discuss pagination, ordering, or result format. With the output schema present, this is minimally adequate but not rich.

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 focused sentence with no filler. It front-loads the core action and resource, then adds a compact note on how the labels are used.

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 operation with an output schema and supported by annotations, the description is sufficient. It names the resource, the returned data (ids), and the purpose (filtering), leaving no critical gap for an agent to 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?

The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description adds no parameter semantics, but none are needed 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 clearly states 'Get all labels with ids', identifying the specific resource (labels) and the expected outcome (IDs for label_ids and filtering). This distinguishes it from sibling getters like get_goals and get_categories without ambiguity.

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 'for label_ids and filtering' implies when this tool is useful, but there is no explicit when-to-use guidance or mention of alternatives. It relies on inference rather than direct instruction.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=false. The description adds useful context about the 1440/day budget and that it is shared by all tools, which goes beyond the annotations and helps the agent understand the scope of the read 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 short but contains redundancy: the second sentence essentially repeats the first, adding only 'shared by all tools' as new information. It could be condensed into one sentence without losing clarity, so it is not as crisp as it could be.

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 tool with an existing output schema and read-only annotations, the description adequately covers the purpose and key detail of the shared daily budget. It does not need to explain return values since the output schema exists, and there are no other complex aspects requiring elaboration.

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 description does not need to explain parameter syntax or meaning. The schema description coverage is 100%, and with no params, the baseline of 4 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 states the tool shows today's Marvin API calls against the 1440/day budget. It identifies a specific resource and verb, and it is distinct from all sibling tools, as no other tool covers rate limit status.

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

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

The description implies the tool is for checking current API usage against a shared daily budget, but it does not explicitly state when to use it or mention alternatives. There are no direct exclusions, but the guidance is only implied rather than explicit.

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

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

Beyond the readOnlyHint annotation, the description discloses an additional side effect—pushing notifications to the phone—and states the authorization requirement. This adds useful behavioral context, though the punctuation leaves some ambiguity about whether the push is part of the tool's behavior or a separate instruction.

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

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

The description is short and front-loads the main action, but the comma splice in 'Get all server-side reminders, push notifications to the phone' creates confusion. A simple conjunction or rewording would make it fully clear.

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

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

For a zero-parameter tool with an output schema and a read-only annotation, the description covers the key extras: the all-reminders scope, the notification behavior, and the Full Access Token requirement. It is adequate, though the wording could be cleaner.

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 schema coverage is complete, so the baseline of 4 applies. There is no parameter detail for the description to add.

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 identifies a clear verb and resource: 'Get all server-side reminders.' The 'push notifications to the phone' clause slightly muddies the core purpose, and it does not explicitly differentiate from siblings like get_due_items, but the primary action is still unambiguous.

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

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

No guidance is given on when to use this tool versus alternatives such as get_due_items or set_reminder. The mention of 'Requires the Full Access Token' is an authentication prerequisite, not 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 cover the read-only and non-open-world behavior, so the description does not need to restate those. It adds the 'source of truth' characterization and the 100-task cap, but does not disclose pagination, ordering, or what historical data is included beyond what the schema and output schema likely convey.

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 contains two sentences that repeat nearly the same information. The second sentence adds only 'source of truth' and the max-100 constraint, which is already implied in the first sentence, so the extra sentence does not earn 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 one-parameter read-only tool with an output schema, the description covers the essential information: what is fetched and the call limit. The remaining context is adequately supplied by the annotations and schema.

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

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

Schema coverage is 100%, and the single task_ids parameter is documented as 'Up to 100 task IDs.' The description repeats that limit ('max 100 per call') without adding examples, batching advice, or additional parameter semantics.

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 time-tracking history' for up to 100 tasks. It is clear enough to identify the tool's purpose, though it does not explicitly distinguish it from related siblings like get_tracked_item or get_today_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?

No guidance is given about when to use this tool versus alternatives such as get_tracked_item, get_today_time_blocks, or start_tracking. The phrase 'source of truth' hints at authority, but there are no explicit conditions, exclusions, or alternatives 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?

Even with readOnlyHint=true and openWorldHint=false, the description adds substantial behavioral context: items earlier than the date are included, deadline-only tasks are excluded, timezone behavior is specified, recurring-task generation caveats are disclosed, and known testing limitations are noted. This goes well 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 core behavior is front-loaded in the first sentence, with clarifying edge cases and caveats following. It is slightly verbose with dated observations and testing notes, but those notes are informative and not redundant 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?

For a read-only tool with one optional parameter and an output schema, the description is highly complete: it covers timezone resolution, scheduling semantics, exclusions, known recurring-task behavior, and testing caveats. Nothing essential is left unstated.

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

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

The schema already describes the only parameter with full coverage, including its format, default behavior, and day <= date semantics. The description restates these details rather than adding new parameter-level meaning, so the baseline 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 opens with a specific verb and resource: 'Get open tasks and projects scheduled today or earlier.' It clearly distinguishes this tool from get_due_items by stating that deadline-only tasks are excluded and belong to that sibling tool.

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

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

The description tells the agent exactly what this tool is for and when not to use it: tasks with only a deadline are not included and should be fetched with get_due_items. It also describes the date-filtering behavior precisely (day <= date), leaving little 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?

Beyond the readOnlyHint annotation, the description discloses a real limitation (MarvinAPI issue #65) and explains the workaround: the mapping is fetched separately from plannerSmartLists using a normalized block title. This is exactly the non-obvious behavior an agent needs to interpret the response and the extra API call.

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

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

Two sentences, front-loaded with the core purpose and followed by a focused limitation note. Every clause contributes either a use case or behavioral context; there is no redundant 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?

Given the readOnly annotation, an existing output schema, and full parameter coverage in the schema, the description covers the tool's main behavioral quirk and mapping semantics. It does not explicitly position the tool against similar siblings such as get_time_tracks, leaving a minor selection 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?

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaning by explaining why include_category_mapping exists and how the mapping key works (normalized block title), which goes beyond the schema's terse '1 extra API call' note.

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: "Get today's time blocks with their category or smart-list mapping." This clearly states what is returned and differentiates the tool from siblings like get_time_tracks by emphasizing the category/smart-list enrichment.

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 described use case is clear: call this when you need time blocks and their category/smart-list mapping for today (or any date via the date parameter). It does not name alternative tools or state explicit when-not-to-use conditions, so it stops one step short of the top score.

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 aligns with the readOnlyHint annotation and adds useful context by specifying that the tool reports the in-progress tracked item rather than historical records. It doesn't contradict annotations, and while it doesn't detail null-return behavior or edge cases, the read-only annotation plus clear present-state wording provide sufficient safety 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?

One short, front-loaded sentence carries full meaning without redundancy. The essential information — current time-tracked task — is delivered immediately, and there is no filler or repetition of the tool name.

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, read-only query tool with an output schema and clear annotations, the description is complete. It tells the agent exactly what the tool returns conceptually, and the output schema handles return-value details, so nothing essential 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 nothing for the description to add beyond the schema. The baseline of 4 applies here because no parameter documentation is needed, and the description accurately conveys what operation will be performed.

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 names the exact resource: which task is currently being time-tracked. This clearly distinguishes it from sibling tools like start_tracking, stop_tracking, and get_time_tracks, which concern tracking actions or historical time-track data.

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 use case by saying 'right now', indicating this tool reports the current tracking state. However, it does not explicitly state when to prefer this over get_time_tracks or how it relates to start_tracking/stop_tracking, leaving the agent to infer the appropriate selection.

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 a key behavioral detail: 'Costs no Marvin API call.' This is beyond what annotations provide and informs the agent about resource usage. Does not contradict annotations. Slightly stronger than baseline because it discloses a practical cost aspect, though no further behavioral details are needed given the simple read-only nature.

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

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

Three short sentences with no fluff. The primary purpose is front-loaded in the first sentence, usage guidance follows, and the caveat about other tools is concise. Every sentence earns its place and the description is highly scannable.

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

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

Given the tool has no parameters and an output schema exists, the description covers all essential aspects: what it lists, when to use it, its cost (free), and a pointer to per-tool details. Nothing an agent needs to decide to invoke it 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?

Tool has zero parameters, so schema coverage is trivially 100%. Baseline is 4 for no parameters. The description doesn't need to explain parameters; it does clarify the output nature ('every Marvin tool by area'), which adds value beyond the empty schema. No gaps.

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 ('List') and resource ('every Marvin tool by area') plus content details ('what it can and cannot do'). Clearly distinguishes itself from all sibling tools, which are operational tools, not a meta-listing tool. No ambiguity about its function.

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 prescribes when to call it: 'Call it before assuming something is impossible via MCP or requires manual work in the app.' Also gives a caveat that detailed live conditions are in each tool's own description, guiding the agent to consult the appropriate tool for specifics. Provides clear context and exclusions.

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

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

Annotations already cover readOnlyHint=true, so the read-only nature is established. The description adds value beyond that by disclosing the auth requirement (Full Access Token) and the behavioral trap of the non-raw endpoint. It doesn't describe the response shape, but the output schema exists to cover that, and no contradiction with annotations is present.

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 first two sentences are redundant — 'Get all habits with title, settings and history' and 'Get all habits as full documents incl. title, settings and history' repeat the same content before adding the format detail. The crucial warning is well-placed at the end, but the opening duplication wastes space.

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 tool with an output schema, the description is nearly complete: it covers the auth prerequisite and the critical pitfall distinguishing it from the non-raw endpoint. The only minor omission is an explicit statement of returned fields beyond the history array, but the output schema carries that burden.

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 takes zero parameters, so the baseline is 4 and the schema is trivially 100% covered. The description compensates by clarifying the return format of the history field ([time1, value1, time2, value2, ...] in unix ms), which informs an agent what to expect without any params to document.

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 precise action ('Get all habits') and explicitly enumerates the returned contents (title, settings, history with time/value pairs). The resource and scope are unambiguous, and it separates a bulk listing from the singular get_habit in the sibling set.

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, live-verified guidance: this tool requires the Full Access Token (raw variant of /habits) and explicitly warns that the non-raw variant is wrong here, explaining why (lazy tracking registry, missing never-recorded habits, no titles). That directly tells an agent when and how this tool must be invoked versus its alternate.

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 exact error semantics (404 vs 400), idempotent behavior, time-tracking side effects, pinned-task behavior, and `day`-field handling. It even notes server-behavior changes over time. This is rich behavioral context that the annotations alone could not provide, and it does not contradict the idempotentHint=true or destructiveHint=false 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 information-dense and mostly valuable, but it opens with two overlapping sentences ('Mark a task as done; projects are completed in the app.' followed by 'Mark a task as done (via /markDone...)'). Several live-testing dates and caveats could be consolidated. Still, the length is largely justified by the many behavioral edge cases.

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

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

For a mutation tool with one parameter, an output schema, and idempotence annotations, the description covers all decision-relevant context: supported vs unsupported resources, error codes, side effects on time tracking, recurring tasks, pinned tasks, and how to read back completed tasks. 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?

The schema already describes item_id as 'Task ID (NOT a project — see description)', and the description reinforces this with details about deterministic recurring-task instance IDs and the distinction from project IDs. Though schema coverage is 100%, the description adds useful value about what kind of ID is valid and how recurring instances are formed.

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

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

The description clearly states a specific action ('Mark a task as done') and resource (tasks), and explicitly distinguishes from projects ('Tasks ONLY: for projects the API responds 400'). It also differentiates from related tools like /doc/update and unmark-related behavior. This leaves no ambiguity about the tool's 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 explicit when-to-use guidance and names alternatives: projects should be completed in the Marvin app, /doc/update would technically work but skips side effects, and get_done_items should be used for listing completed tasks. It also covers edge cases like recurring-task instances and error conditions, so an agent can decide when to invoke this tool versus others.

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

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

Annotations already signal a mutating, non-idempotent operation. The description adds a useful side effect: it updates the sync database (updateDB=true) so the Marvin app shows the change immediately. This is beyond the structured hints, though the cryptic 'updateDB=true' parenthetical introduces a name not present in the input 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?

Two sentences, with the primary action front-loaded and no filler. The second sentence earns its place by disclosing the sync side effect, though the parenthetical updateDB=true is unnecessarily cryptic and could be simplified.

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?

This is a simple tool with full schema coverage and an output schema, so the description does not need to restate return values. It covers the action and the key side effect, leaving only the when-to-choose guidance under-specified.

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

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

Schema description coverage is 100%, so the baseline is 3 even without description-level parameter detail. The description does not add meaning to habit_id, undo, or value; its only parameter-adjacent mention, updateDB=true, is not an actual input parameter and could confuse rather than clarify.

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

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

The first sentence states a specific verb and resource: 'Record or undo a habit check-in.' This clearly identifies the operation and distinguishes it from task-focused siblings like mark_done or unmark_done. However, it does not explicitly contrast itself with sibling tools, so it stops 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 description gives no explicit guidance on when to use this tool versus alternatives such as list_habits/get_habit for reading habits or mark_done/unmark_done for tasks. The 'undo' option hints at one usage scenario, but there is no when-to-use or when-not-to-use guidance.

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

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

The description discloses exactly what happens: the entire earn/spend history is deleted and balance is set to 0, and this is permanent. It also adds the auth context (Full Access Token) and goes beyond the destructiveHint/idempotentHint annotations by spelling out the concrete consequence, so an agent can anticipate the irreversible side effect.

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 key consequence (permanently deletes history, sets balance to 0) front-loaded. There's minor redundancy in repeating 'permanently' at the start and in the second sentence, but the warning is important enough that the emphasis is acceptable and no extraneous detail is present.

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 destructive operation with a provided output schema, the description fully covers the operational effect, irreversibility, authorization requirement, and appropriate invocation condition. Nothing relevant to a safe call 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 takes zero parameters, and the schema covers this completely, so no parameter-level explanation is needed. The baseline for a no-parameter tool is 4, and the description appropriately focuses on the operation's effect rather than input 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 names a specific operation (reset reward points) and precisely defines the scope: deletes the whole earn/spend history and sets balance to 0. This clearly differentiates it from sibling reward tools like claim_reward_points, unclaim_reward_points, and spend_reward_points, which affect only parts of the reward balance.

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 a clear condition: only use when the user explicitly asks for a reset, and warns it cannot be undone. It doesn't explicitly contrast with sibling reward operations (e.g., use spend_reward_points for a normal deduction), but the irreversibility warning and explicit-request condition are strong enough 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds substantial behavioral context beyond annotations: the isStarred mapping (3/2/1/-1) verified against app code, the 'Enable low priority' strategy caveat, the fact that low priority is stored regardless of display, the project-vs-task distinction, and the non-standard 500 error behavior. This is rich, verified behavioral disclosure that goes well beyond the 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?

The description is dense but every sentence earns its place: it covers scope, authentication, value semantics, project exclusion, and error behavior. It is front-loaded with the core action and resource. Slightly long, but the length is justified by the verified behavioral details that prevent misuse.

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 (two optional markers, a non-obvious isStarred encoding, a project-vs-task distinction, and a non-standard error code), the description is complete. It covers what the tool does, when to use it, what the values mean, what doesn't apply, and how to interpret failures. The output schema exists, so return values need not be described.

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

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

Schema description coverage is 100%, so the schema already documents both parameters with their value mappings. The description adds value by explaining the semantic meaning of the priority levels in app terms (Most/Very/Important/Low), the frog marker concept, and the low-priority display caveat. It doesn't repeat the schema's numeric ranges but enriches the meaning, which is exactly what the description should do.

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 ('Set'), a specific resource ('priority (P1-P3 or low) or the frog marker on a task'), and explicitly distinguishes from projects ('Does not apply to projects... set it via update_category_or_project'). It clearly identifies the target as an existing TASK and names the sibling tool for the alternative case, so an agent can select it correctly.

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 when-to-use guidance: it applies to tasks, not projects, and names the alternative tool (update_category_or_project) for projects. It also discloses the prerequisite (Full Access Token) and the error condition (permanent 500 = task does not exist), which helps the agent decide when to call this tool and when to fetch a fresh ID 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?

With all annotations false, the description carries the full burden and delivers extensively: it discloses the two-write data integrity hazard, that this tool only writes the server-side entry, that setting reminder_id to a task ID will not link in the UI, and that it can create orphaned entries. It also adds MCP limitation context about task times, far exceeding a minimal schema description.

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 verbose and repetitive: the standalone-reminder statement appears twice, and the 'Facts about time on tasks' section is tangential to invoking the tool. It is organized with a warning block, but several sentences could be trimmed without losing necessary 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 tool with a write side effect and serious data-integrity caveats, the description covers prerequisites, exclusions, side effects, and failure modes (orphaned entries). Combined with a complete input schema and an output schema, an agent has everything it needs to call this correctly and avoid misuse.

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, but the description adds critical semantics for reminder_id by explaining the two-write mechanism and why a task ID must not be used. It also clarifies the constraint that task times are not set here, which helps interpret time_unix_seconds. This exceeds the baseline for fully-covered schemas.

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 the specific action — setting a standalone push reminder — and explicitly contrasts it with task-linked reminders, saying 'Task-linked reminders are set in the Marvin app; use this tool for standalone reminders only.' This clearly distinguishes it from sibling tools like create_task and delete_reminder.

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 (standalone push reminders only) and when not to (task-linked reminders). It also names the prerequisite that the Marvin mobile app must be logged in and warns against using a task ID as reminder_id. This is explicit routing guidance relative to the sibling tools.

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

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

Beyond the annotations, the description discloses a verified failure mode: the API returns 500 if the balance would go negative, and it directs the agent to get_account_info first. This is valuable behavioral context that annotations alone do not 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?

Two sentences carry the entire definition with no filler. The core action is front-loaded, and the critical warning is placed immediately after, making the description easy to scan and 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?

The definition is nearly complete for invocation: the schema fully documents parameters, an output schema exists, and the description supplies the most important operational caveat. The only mild gap is that 'a reward' is not explicitly defined or parameterized, but this does not block 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?

The input schema already describes both parameters with 100% coverage, so the description adds little parameter-level meaning. The phrase 'large purchases' vaguely relates to the points amount, but it does not clarify format, constraints, or semantics 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 states the operation: spending reward points on a reward. It uses a specific verb and resource, making the tool's purpose unambiguous, and the phrase 'on a reward' helps distinguish it from related point-management operations. It does not explicitly name a sibling tool for contrast, 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 provides an explicit precondition: check the balance via get_account_info before large purchases to avoid the 500 error. This is clear, actionable usage guidance. It does not, however, discuss when not to use this tool or when an alternative should be chosen.

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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description adds no behavioral context beyond the action itself. It does not disclose side effects (e.g., whether it creates a new time track or overwrites an existing one) or requirements like authentication. The idempotency hint is useful, but the description does not elaborate on 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 a single sentence with no filler. It is front-loaded with the action and resource, and no information is extraneous.

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 tool with an output schema and annotations covering safety, the description is minimally adequate. However, it does not provide workflow context (e.g., that it pairs with stop_tracking) or mention any preconditions. The existence of an output schema reduces the need for return-value explanation.

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 task_id described as 'Task ID', so the schema carries the meaning. The description does not add any additional context about the parameter, but the baseline of 3 applies since the schema is sufficient.

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

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

The description clearly states the action 'start time tracking' and the resource 'a task'. It distinguishes itself from the sibling 'stop_tracking' by describing the opposite operation. However, it lacks specificity about what 'time tracking' entails or what constitutes a task state.

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 alternatives. There is no mention of conditions for starting tracking, prerequisites (e.g., task must exist), or exclusions. The description only states what it does, not when to use 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?

Beyond the annotations, the description discloses a significant behavioral quirk: task.times/duration fields are not updated, and tracking only appears in get_time_tracks/tracks. It also records the side-effect exception for mark_done, giving the agent accurate expectations about where data lands. This strongly exceeds what readOnlyHint, idempotentHint, and destructiveHint already convey.

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 and well organized, but the first two sentences repeat the same message almost verbatim: 'Stop time tracking on a task' and 'Stop time tracking for a task.' The API limitation note is valuable, but the duplication means not 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 one-parameter, idempotent, non-destructive mutation with an output schema, the description covers the result location, a documented API limitation, and the mark_done exception. It does not need to explain return values because an output schema exists, and the idempotentHint covers repeated-call expectations.

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 for the single task_id parameter is 100%, so the description does not need to compensate. It adds some context by referring to 'the task's own times/duration fields,' but it does not add parameter-level format or meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Stop time tracking on a task.' It clearly differentiates from siblings by naming where the tracking lands, get_time_tracks, and by noting the opposite behavior of mark_done. The action could not be confused with start_tracking or reading tools.

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

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

The description gives clear context for when the tool is used: when time tracking on a task should be stopped. It also provides an important conditional exception involving mark_done, though it does not explicitly spell out 'use this instead of X' beyond the implied contrast with start_tracking.

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 meaningful behavioral context by specifying that a successful check returns OK if the API token works. This clarifies the tool's non-destructive auth-testing behavior beyond what annotations alone state.

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 only two short sentences, front-loading the core purpose ('Check that the API token works') and then specifying the success result. Every word contributes value, with no redundancy.

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

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

For a zero-parameter, read-only connectivity check with an output schema present, the description fully covers what an agent needs to invoke it correctly. The safety profile is captured by annotations, and return semantics are succinctly stated.

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 of 4 applies. The description mentions apiToken conceptually, but since there is no schema to document, no parameter-level detail is needed or missing.

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

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

Description uses a specific verb ('Check') with a clear resource ('API token' against Marvin's API) and states the expected result ('Returns OK if the apiToken works'). This clearly distinguishes the tool from sibling tools like get_account_info or get_rate_limit_status.

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

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

The description implies the tool is for verifying API token validity but provides no explicit guidance on when to choose it over alternatives. No sibling exclusions or conditions are given, so an agent must infer usage from the tool name and description alone.

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 annotations, the description discloses that only real task IDs work, that manual awards have no server entry, that the endpoint responds 404 for manual awards, and that spend_reward_points is the correct compensation path. This adds valuable behavioral context not present in the structured annotations.

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

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

The description is front-loaded with the core purpose and then provides use cases, limitations, and an alternative. There is slight redundancy between the opening sentence and the second sentence ('Undo a reward-point award' vs 'Undo a point award'), but the structure is otherwise tight and scannable.

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

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

The tool description covers purpose, trigger scenarios, constraints, error behavior, and alternative handling for manual awards. Since an output schema exists, not detailing return values is acceptable. The description is complete for correct invocation and handling of edge cases.

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 to item_id by clarifying it is a task ID that determines the point amount and that MANUAL is not supported. This goes beyond the schema's basic description, so a 4 is warranted.

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: 'Undo a reward-point award tied to a task.' It clearly distinguishes itself from sibling tools like claim_reward_points and spend_reward_points by focusing on undoing awards and explicitly calling out the unsupported MANUAL case.

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 concrete when-to-use scenarios ('after a misclick', 'when the task was un-completed with unmark_done') and an explicit when-not-to-use case (MANUAL awards) with the exact alternative (spend_reward_points for the same amount). This is exemplary 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: it requires the Full Access Token, works on generated instances of recurring tasks, does not adjust kudos, and documents the verified 500-on-missing-document behavior. This goes beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded with the core action, then adds necessary caveats. Each sentence earns its place, though the error-code detail is slightly verbose for a tool 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 single-parameter mutation tool with an output schema and annotations covering idempotency and destructiveness, the description is nearly complete. It covers auth requirements, edge cases (recurring tasks, kudos), and error behavior. The only minor gap is not describing the success response shape, but the output schema likely covers that.

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 the only parameter, item_id, is already described as 'Task ID'. The description does not add further meaning to the parameter beyond what the schema provides, 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?

The description clearly states the verb 'Undo' and the resource 'a task's completion', and specifies the exact effect (sets done=false and clears doneAt via /doc/update). It distinguishes itself from mark_done and unclaim_reward_points, so an agent can tell it apart from siblings 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?

The description explicitly notes when to use it (to undo a completion) and names the alternative for undoing reward points (unclaim_reward_points). It also warns about the 500 error case for non-existent documents, giving clear context for when the tool may fail.

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 substantial behavior beyond the annotations: it discloses a hidden pre-read API call when Projects-ONLY fields are supplied, explains that the tool refuses categories in that case, and gives a precise failure-mode distinction between transient 500s (retry) and permanent 500s (missing document). It also warns that completion via /doc/update skips app side effects. This is consistent with idempotentHint=true and not contradicted by any 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?

The description is front-loaded with a clear one-sentence summary and sibling routing, followed by well-separated operational warnings. It is longer than average, but the tool is complex and the extra length covers genuine behavioral hazards. It loses a point for some redundancy with schema details (repeated field lists and numerous verification dates) that could be trimmed without losing meaning.

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 tool with a rich input schema and an output schema, the description covers the non-obvious operational context: full-access-token requirement, category blocking logic, strategy-disabled behavior, completion side effects, and the 500-as-missing-ID failure mode. An agent has everything it needs to invoke this tool correctly and to interpret common failures.

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 baseline is 3. The description adds value above the schema by grouping parameters into 'Projects ONLY' vs. shared fields, clarifying that label_ids applies to both categories and projects, and noting that strategy fields work even when the strategy is disabled. It does not need to enumerate every parameter because the schema already does that thoroughly.

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: 'Update a category or project' and lists the editable fields (labels, color, icon, note, project fields). It explicitly distinguishes itself from the sibling tool: 'For tasks, use update_task.' An agent can determine what this tool does and what it does not do without reading 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?

It gives explicit routing guidance: tasks go to update_task, projects must not be completed here, and Projects-ONLY fields are blocked for categories. It also clarifies that strategy-dependent fields can be set even when the strategy is disabled, which prevents an agent from wrongly assuming a prerequisite. The 'existing CATEGORY or PROJECT' wording plus 'For tasks, use update_task' provides clear when-to-use and when-not-to-use signals.

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, disclosing the /doc/update write endpoint, Full Access Token requirement, MCP limitation around clock time/reminders, strategy-disabled fields still being settable, and the 500-vs-missing-ID server behavior. It also explains that a permanent 500 means a non-existent document. These are valuable behavioral traits not visible in the schema or 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 long, but it is densely informational and every sentence adds decision-relevant context. It is front-loaded with the core purpose, then covers routing, limitations, recurring-task warnings, and error semantics in a logical order. For a complex 23-parameter mutation tool with many verified edge cases, this length is justified.

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, the rich schema, and the output schema, the description is complete: it covers auth, sibling routing, strategy interactions, recurring-task rules, and server error behavior. It does not need to explain return values because an output schema exists. Nothing critical 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?

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all 23 parameters in detail. The tool description adds a high-level field list but does not need to repeat per-parameter semantics. The schema's parameter descriptions carry the load effectively.

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 'Update a task: title, day, deadline, labels, note, estimate, sections,' a specific verb plus resource. It explicitly routes category/project updates, priority changes, and completion to sibling tools, distinguishing update_task from update_category_or_project, set_priority, and mark_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 explicitly says when to use alternatives: 'For categories/projects, use update_category_or_project. For priority, use set_priority. Always complete tasks via mark_done, never here.' It also gives strong do-not-use guidance for recurring-task recurrence rules, telling the agent to edit those in the app.

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