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?

With annotations already declaring non-readOnly, non-destructive and non-idempotent, the description adds genuinely new behavior: the category path requires a Full Access Token via /doc/create, project titles containing '#word' are blocked locally by the client before any API call because of an /addProject corruption bug, and /addProject silently ignores color and startDate/endDate. These are exactly the silent-failure disclosures 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?

Purpose is front-loaded, but the prose is bloated with parenthetical verification dates ('live-tested 2026-09-11', 'verified live 2026-08-29') and restates constraints that already appear in the schema descriptions, such as the color and day/due_date restrictions. The startDate/endDate paragraph discusses fields that are not parameters of this tool, adding noise.

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

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

An output schema exists, so return values need not be explained. For a 15-parameter mutation tool with rich annotations, the description covers auth requirements, silent-ignores, and a local validation block, leaving only minor gaps (e.g., what happens on an invalid kind/field combination).

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 carries the per-parameter meaning, and much of the description's field commentary (color Categories ONLY, day/due_date blocked for categories, label_ids applies to both) duplicates it nearly verbatim. The description adds little parameter meaning beyond the schema, 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 opening sentence states a specific verb (Create) and the two resources (category or project) along with the fields it accepts. It also makes the structural distinction between the two kinds explicit (categories can contain categories; projects cannot), which lets an agent tell this apart from create_task and update_category_or_project without opening a schema.

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

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

It gives real routing guidance: use update_category_or_project afterwards for startDate/endDate, since /addProject ignores them at creation, and it explains why certain fields (day/due_date/priority/frog) are rejected for kind='category'. It never contrasts with create_task for task creation, so it stops short of fully explicit when/when-not/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 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 already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description goes beyond them by disclosing that the tool relies on undocumented/experimental writes (/doc/create, /doc/update) and that the shape is pinned to app 1.71 — valuable fragility and reliability 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?

Purpose is front-loaded in the first sentence, followed by the exclusion rule and then the experimental-writes caveat. It runs to three sentences but each carries distinct value; the technical note about undocumented endpoints 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?

With an output schema present, return values need not be explained, and annotations cover safety. The description adds the exclusion logic and reliability caveat, leaving little an agent would need to call it correctly, though the positive use-case trigger could be sharper.

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 both parameters (title, sections) are already documented in the schema. The description only echoes 'optionally with sections' and adds no format or syntax detail beyond the schema, 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?

States a specific verb and resource ('Create a standalone notebook, optionally with sections') and explicitly scopes what it does not create. It distinguishes itself from create_category_or_project and the notebook-page tools without the reader needing to open a schema.

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

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

Gives a clear when-not-to-use rule: project/category notebooks are not created here but come into being when a page is moved (update_notebook_page move_to_parent_id) or a second page is added. The alternative mechanism is named, though it doesn't spell out the positive trigger condition as crisply.

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 the mutation/non-idempotent/non-destructive profile, but the description adds meaningful context beyond them: the page ranks after existing pages, the '- ' to '* ' marker rewriting (list-deletion protection), and notably that it depends on undocumented, experimental endpoints matched against app 1.71. That fragility warning is genuinely valuable. It stops short of auth or error behavior.

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

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

Front-loaded with the core action and placement, then progressively discloses behavioral quirks and dependency risk. Four sentences, each carrying distinct information; only minor tightening possible.

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?

Output schema exists so return values need not be explained, and full schema coverage handles parameters. The description completes the mutation picture with ordering, text transformation, and endpoint fragility. Missing only ancillary details like required permissions or rate-limit 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%, so parameters (notebook_id, title, text, section_id) are already documented. The prose only loosely restates placement ('notebook', 'section') and adds no syntax or format detail beyond the schema, 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?

States a specific verb and resource ('Create a page') plus precise placement scope ('at the end of a notebook, optionally in a section'). This clearly distinguishes it from siblings like create_notebook, update_notebook_page, and delete_notebook_page without needing to open any schema.

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

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

The placement semantics ('at the end of a notebook, optionally in a section') imply when this tool is appropriate versus adding elsewhere, but there is no explicit when-to-use vs alternatives routing (e.g., update_notebook_page). Usage is implied rather than stated.

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

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

Annotations cover only the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds extensive behavior: occurrences are materialized when a client next opens after midnight rather than immediately, defaults apply when create_occurrences is omitted, first occurrence is written on the start day even if future, and inherited fields (label, priority, size, note, subtasks, sections, hard deadline) are enumerated and flagged as API-verified.

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

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

The purpose is front-loaded and each paragraph carries distinct information about timing, inheritance, and weekend rules. It is dense but not padded, though the RRULE example and the only_weekdays caveat are near-duplicated from the schema, which is a minor redundancy rather than true waste.

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

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

With an output schema present, return values need no explanation, and the description covers the tricky semantics an agent would otherwise get wrong: deferred occurrence creation, default fallbacks, parameter-type coupling, and weekend edge cases. Nothing required to call the tool correctly across its 24 parameters is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it maps each repeat enum value to its required companion parameter and to the dialog type, explains custom requires an RRULE string, and annotates only_weekdays edge behavior as 'verified' (weekend month-day moves to Friday) versus 'inferred' (every_x_days counting weekdays). This goes beyond restating schema text.

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

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

The opening sentence states a specific verb (Create) and resource (recurring task) and bounds the scope to the app's eleven repeat-dialog types, which cleanly distinguishes it from create_task and update_recurring_task. An agent can identify what this produces without opening the schema.

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

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

Usage is implied through the repeated framing of the in-app 'repeat dialog' and the note that omitting create_occurrences falls back to the account default, but the description never explicitly names an alternative (e.g. create_task for non-recurring items) or states when-not-to-use. The agent must infer routing from the pervasive dialog 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 only say it is not read-only, not idempotent and not destructive; the description goes well beyond them by disclosing that shortcut parsing is disabled (X-Auto-Complete: false), that size/subtasks/time/reminders are written in a second step via /doc/update and /reminder/set, and that a partial failure leaves a task that already exists with the response naming which steps succeeded. That partial-success semantics is exactly the kind of behavioral trait an agent must know to avoid duplicating a task.

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 action is front-loaded in one short sentence before the caveats, which is the right ordering for a 23-parameter tool. The remaining text is dense and clause-heavy with parenthetical asides, but each statement carries operational information rather than 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?

An output schema exists so return values need not be explained, and the description still covers the important exception: partial-step failure reporting. For a creation tool with heavy strategy-dependent fields and a two-phase write, the non-obvious cross-field constraints are surfaced, though the relationship to sibling creation tools remains unaddressed.

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 every parameter carries a detailed description, so the schema already does the heavy lifting and a 3 is the baseline. The description reinforces a few cross-cutting rules (clock time requires day, strategy-dependent fields are stored even when the strategy is off) but adds no per-parameter syntax or format detail beyond what the schema supplies.

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

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

The opening sentence states a specific verb and resource plus the field families it accepts ('Create a task with category, day, priority, size, time and reminders'), so an agent can identify it immediately. It does not name or distinguish itself from near siblings such as create_recurring_task or create_event, which is the only gap.

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 routes some work elsewhere ('startDate/endDate are set with update_task afterwards', 'Use the parameters instead' of inline shortcuts), which is genuine when-to-use guidance. However, there is no explicit statement of when to prefer this over create_recurring_task/create_event, nor of prerequisites such as needing a day before a clock time presented as a usage rule.

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?

Beyond the destructive/idempotent annotations, it discloses the internal deletion order (pages first, then notebook), the absence of trash, the text-preservation write-back to the parent project/category note, and reliance on undocumented experimental endpoints pinned to app 1.71. This is exactly the behavioral context annotations can't 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?

Front-loaded with the core action and information-dense with no filler, so every sentence earns its place. However the 'Two steps:' sentence is grammatically tangled and requires a re-read, slightly hurting 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?

An output schema exists so return values need no prose. For a destructive, side-effect-heavy mutation, the description covers prerequisites, ordering, data preservation, and fragility — nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the conditional circumstances under which confirm must be true and what the first (non-confirming) call returns (title, size, first line). That materially changes how an agent sequences calls.

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 up front ('Delete a notebook and its pages permanently') and clarifies scope versus the page-level sibling delete_notebook_page. An agent knows exactly what is removed and that no trash/recovery path exists.

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

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

Gives explicit conditions for when confirm=true is required (parented notebook with >1 page; standalone notebook with any text page) and describes the two-step confirm dance. It does not explicitly name alternative tools (e.g. delete_notebook_page) to route between, which keeps it short of a 5.

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

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

Beyond the annotations (destructive/idempotent), it discloses that there is no trash via the API (permanent deletion), the two-step confirm workflow and what the first call returns, the parent's first-page pointer behavior, and that it relies on undocumented writes ('/doc/create', '/doc/update') matched to app 1.71. This is unusually rich behavioral context and is consistent with destructiveHint=true and idempotentHint=true.

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

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

Purpose is front-loaded in the opening clause, followed by edge cases and the implementation caveat. Dense and slightly long, but each sentence carries a distinct constraint (trash, confirm, last page, first-page pointer, experimental writes), so little is wasted for a destructive tool with tricky semantics.

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

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

An output schema exists, so return values need not be described. Combined with the permanence warning, confirm workflow, routing to delete_notebook, and the undocumented-writes disclaimer, the description covers everything an agent needs to call this 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that confirm=true is the gate for deleting a page with text and that the preceding call surfaces title, size and first line. That workflow context goes beyond the schema's terse confirm description.

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

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

States a specific verb+resource ('Delete a notebook page permanently') and immediately distinguishes itself from the sibling delete_notebook by scoping the last-page case. An agent can tell exactly what this does and what it does not handle.

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

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

Explicit when-to-use and when-not-to-use: 'The last page of a notebook with a parent is not deleted here — use delete_notebook.' It also explains the conditional confirm flow (a page with text requires confirm=true). Nothing is left 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 destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: the dual-removal requirement (list + server), the side effect that a stale list entry makes an open client notify, and the special-case for type T reminders. This is exactly the behavioral depth an agent needs for a destructive 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?

Front-loads the core action and then elaborates on the task_id distinction and the type T exception. Slightly dense across several clauses, but every sentence carries actionable information with no filler.

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

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

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies the branching logic, side effects, and edge case needed to invoke this destructive tool correctly, leaving no meaningful gap.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: task_id controls whether removal is local-list-only or also cascades from the server, and it explains the consequence of the cascade. That is more than the schema's one-line parameter doc conveys.

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 (delete) and resource (reminders) and goes further by distinguishing the two operating modes (with vs without task_id). An agent can immediately tell this is a deletion tool scoped to reminders, distinct from set_reminder/get_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 says when to pass task_id (task-owned reminders, both list and server removal) versus when to omit it (standalone reminders or orphaned entries from get_reminders). It also routes the agent to an alternative for the special clock-time reminder type T (update_task(time='')).

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 destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: trash bypass, reminder/server-entry cleanup before deletion, partial-failure reporting, the pre-flight /children read that can add a call, completed-children left orphaned, and the stale-client recreation hazard. This is exactly the extra context destructive operations need.

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 critical warning is front-loaded, which is good, but the body is a dense wall of prose with a mid-block all-caps label and repeated restatement of the scope enum. The content is substantive, yet it is longer and less scannable than it needs to be for a two-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?

An output schema exists, so return values need not be described, yet the description still covers partial-failure reporting, the notebook-id handoff, and the client reload hazard. For a destructive, non-idempotent-looking operation, nothing an agent needs to call it safely 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 item_id and the scope enum are already documented in the schema, and the description's 'this'/'all' explanation largely restates it. It adds only marginal detail (the recurring task's own id accepted only with 'all', which the schema also 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?

Opens with a specific verb and resource plus a crucial qualifier ('permanently, with no trash and no undo'), and immediately distinguishes scope: tasks and recurring occurrences here, habit recurrences excluded, and the project notebook handed off to delete_notebook. An agent can tell it apart from delete_notebook, delete_reminder and update_task without opening any schema.

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

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

Gives an explicit gate ('use only when the user explicitly wants a deletion'), states when the tool refuses (projects/categories with open children), names the sub-case behavior for 'this' vs 'all', and routes the notebook cleanup to a sibling. That is when-to-use, when-not, and alternatives in one pass.

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 only declare readOnlyHint and openWorldHint, leaving the description to carry behavioral weight. It discloses substantive traits: which recurring occurrences are filtered, that results are cached until local midnight, and that app-side changes may lag by a day — genuine operational context an agent needs to interpret staleness.

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

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

The purpose is correctly front-loaded in sentence one. However, the middle sentences are dense and jargon-laden ('Keep just one (carry)', 'Only the current one (skip) is not filtered here'), so some sentences obscure more than they earn.

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 query with an output schema and complete annotation coverage, the description supplies everything needed: scope, recurrence filtering, caching/staleness, and the hidden-item behavior. Return-format details are correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning to include_hidden by explaining the underlying 'Keep just one (carry)' filter it toggles. The 'by' parameter gets no extra meaning, but the added filter semantics push this 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?

States a specific verb+resource+scope: 'Get open tasks and projects with a deadline today or earlier.' The scope is precise, but it never references the sibling get_today_items, whose overlap with this tool ('deadline today or earlier' vs. today's items) is left for the agent to infer.

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

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

The description explains internal filtering behavior but never states when to choose this tool over get_today_items, get_done_items, or get_tracked_item. No prerequisites, no explicit exclusions, no alternative naming — the agent must infer selection from scope 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?

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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral detail beyond that: page text is returned in rank order, the parent's note is the first page, and truncation at max_chars is reported back with an indication of which pages were dropped. Auth requirements and any rate limits are not mentioned, keeping it from a 5.

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

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

Four short sentences, none wasted, with the core action front-loaded in the first clause. The constraint about exactly one id follows immediately, and truncation behavior is last. Line wrapping splits sentences awkwardly but the content is tight.

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

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

An output schema exists, so return-value detail is not required here. The description covers the two retrieval modes, the id-exclusivity rule, page ordering, and overflow handling, which is enough for correct invocation. Minor gaps such as what happens if no id is supplied leave it just short of complete.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description meaningfully exceeds it by stating the mutual exclusivity of the three id parameters and explaining what parent_id resolves to (a project's or category's note). It also restates max_chars truncation semantics, which the schema covers only as a cap. Marginal added value over the schema, hence 4.

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

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

The description states a concrete verb and resource: 'Read a notebook including the text of its pages, or a single page.' This is clearly distinct from list-style siblings such as get_notebooks, and the mention of page text signals the depth of retrieval. It stops short of naming a sibling it should be preferred over, so it falls short of a 5.

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

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

It gives an explicit invocation rule: 'Give exactly one of notebook_id, parent_id (project/category) and page_id,' which tells the agent how to choose among the identifier modes. The parent_id option is annotated with its meaning ('project/category'), clarifying when that route applies. There is no explicit statement of when to prefer search_notebooks or get_notebooks instead, so it is not a full 5.

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

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

Annotations only cover readOnlyHint and openWorldHint, but the description adds substantial behavioral context beyond them: parent_id/parent_type semantics, updated_at edit behavior, parent_missing/parent_done flags, and an explicit cost model (2 calls, plus one per distinct parent missing). The call-cost disclosure is particularly valuable for planning.

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

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

Front-loaded with the core purpose, and every sentence carries information (parent semantics, updated_at, text routing, missing/done flags, cost). It is dense and the trailing cost sentence is complex to parse, which keeps it from a 5, but there is no filler.

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

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

An output schema exists, so return values need not be explained, yet the description still covers the output-relevant semantics (parent fields, flags, updated_at). For a zero-param, read-only list tool this is complete for correct invocation and interpretation.

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

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

The tool takes zero parameters, so the baseline is 4. There are no arguments to document and the description correctly spends its text on output semantics instead.

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 ('List all notebooks') plus the exact scope ('with page titles, order and sections, without text'). It explicitly routes the agent away from itself for a related need ('For text: get_notebook'), so it is distinguishable from siblings get_notebook and search_notebooks.

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?

Clear context for when to use it (overview listing without page text) and names the alternative for full text (get_notebook). It does not address when to prefer search_notebooks over a full list, so no explicit exclusion is given, keeping it below a 5.

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

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

Annotations already establish readOnlyHint=true/openWorldHint=false, and the description goes further by disclosing the shared budget semantics, cross-client counter behavior, the last-minute activity heuristic, and that this call is free against the budget. These are genuinely useful behavioral traits 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 key facts are front-loaded and the description is short. The first two sentences restate the same action ('Show today's Marvin calls' vs 'Show how many Marvin API calls have been made today'), a minor redundancy that keeps it just under a 5.

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

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

An output schema exists, so return values need no prose explanation, and the description covers budget semantics, sharing, and cost. Complete enough for a no-arg monitoring tool; only the absence of explicit usage-trigger guidance keeps it from a 5.

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

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

There are zero parameters, so per the rubric the baseline is 4. The description correctly implies the tool takes no arguments, leaving nothing for the schema 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 opening sentence states a specific verb and resource — showing today's Marvin API call count against a budget plus the last call time. This is a distinct monitoring tool with no realistic sibling overlap, so an agent can identify it immediately.

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 supplies clear operational context (check the shared 1440/day budget, detect other active clients within the last minute) but does not explicitly frame when to call it versus continuing work, nor any 'do not use' conditions. Usage is strongly implied rather than stated as routing rules.

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?

Much richer than the readOnlyHint/openWorldHint annotations: it discloses recurrence filtering modes (carry/skip/keep all), that the mode is read/cached until local midnight, the fallback when the mode can't be read, and the significant caveat that occurrences are only created once a client opens after the day rolls over. This is exactly the kind of behavior an agent could not infer from structured fields.

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

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

The core purpose and scope constraint are front-loaded, and every paragraph carries information the agent needs. It is dense and unstyled, with the recurring-mode sentence bordering on implementation detail, but nothing is truly wasted.

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

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

An output schema exists, yet the description still explains the notable return fields (hidden_count, which items were hidden, habit_task_ids) and the timing caveat about missing occurrences. For a read tool with a filtering quirk, nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it ties include_hidden to the app's hiding modes and reinforces the 'day <= date' semantics of the date parameter beyond the schema wording, so the agent understands the interaction between the two params.

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

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

States a specific verb and resource ('Get open tasks and projects scheduled today or earlier') and immediately clarifies the subtle scope ('day <= the date, not only exactly on the date'). It also names the sibling that covers the other case ('Deadline-only items: get_due_items'), so an agent can distinguish it without opening any schema.

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

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

Explicitly routes the deadline-only case to get_due_items and explains when to set include_hidden=true. It doesn't address how it relates to other near-neighbors (get_done_items, get_tracked_item, get_today_time_blocks), but the primary ambiguity is resolved.

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?

With annotations present the bar is lower, yet the description goes well beyond them: it enumerates exactly what is removed (server entries T and M, reminderTime cleared, reminders list kept), how habits are recorded, how recurring occurrences shift, that running time tracking is stopped and written to task.times, and the notable gaps (/markDone does not set workedOnAt or stamp fieldUpdates). That is unusually rich side-effect disclosure 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 paragraph is long and dense, but nearly every sentence carries behavioral information rather than filler, and the core action is front-loaded ahead of the edge cases. A tighter grouping of the habit/recurring/future-day branches would read better than the current run-on flow.

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

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

An output schema exists so return values need not be explained, yet the description still tells the agent that partial failures report which steps succeeded. Combined with the edge-case coverage for habits, recurring tasks, and future days, an agent has everything needed 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics for `value`: it defines the habit-with-count case, that the value is recorded with the current time, and that the task only closes once the day's total reaches the target. `item_id`'s task-not-project constraint is reinforced in prose as well.

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

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

States a specific verb+resource ('Mark a task as done') and immediately scopes it by naming the sibling it is not: 'tasks only ... projects are closed with mark_project_done'. An agent can distinguish this from mark_project_done, unmark_done, and record_habit without opening any schema.

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

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

Explicit routing rules: projects get a 400 here and must use mark_project_done; 404 vs 400 are decoded; habit and recurring cases are given their own conditions. This is genuine when/when-not guidance, not 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?

Far exceeds the annotations: it discloses that step 1 writes nothing, the exact /doc/update fields applied (done, doneAt, workedOnAt, day, doneDate), that dueDate is deliberately untouched, that children are closed via /markDone without workedOnAt or fieldUpdates, that a stale code aborts silently, and that partial failure leaves the project open with a per-target report. It also notes the tool intentionally bypasses the app's refusal to close projects with open children. No contradiction with the given hints (closing is reversible via app undo, so destructiveHint=false holds).

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 two-step model is front-loaded and the remaining content is dense edge-case and cost detail, most of which earns its place. It is a long, single-block paragraph with a few expendable clauses ('as the app does', repeated /markDone caveats), so it is slightly heavier than strictly necessary but far from padded.

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

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

For a destructive-but-reversible two-phase tool with an output schema present, the description covers everything the agent needs: preconditions, abort conditions, per-step call costs, partial-failure semantics, and reversal path. Return-value formatting is correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics on top: confirm_code is not just an opaque string but the artifact of step 1, and its absence changes the tool from a read into a no-write preview, while a stale code produces a re-listing rather than an error. That meaning goes beyond what the schema property text conveys.

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

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

Opens with a specific verb and resource: 'Close a project and its open tasks, in two steps.' It immediately distinguishes itself from the sibling mutators (mark_done, unmark_done, update_category_or_project) and explicitly notes that unmark_done refuses projects and completed projects don't show in get_categories. An agent can tell what this does and what it is not without opening the schema.

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

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

Explicit when-to-use guidance via the two-step protocol: step 1 without confirm_code only reads and returns a code; step 2 with the code performs the close. It names preconditions to clear first (sub-projects, habit tasks, recurring occurrences) and the alternative for reversal ('Undo in the app; unmark_done refuses projects'). Nothing about selecting or sequencing the tool is left 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 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses substantive behavioral traits: text is cached in memory, only notebooks with pages changed since the last search (updated_at) are re-read, a hard cap of 20 notebooks per call, a not_searched list for pending notebooks, and per-hit status codes (parent_missing, parent_done). This is exactly the operational context an agent cannot get from structured fields.

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

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

The purpose is front-loaded ahead of the caching/continuation mechanics, and there is little wasted text. The second half is dense and slightly elliptical (e.g., 'fetched with one call' is ambiguous), but every sentence carries information the agent needs.

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

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

With an output schema present and annotations covering the read-only profile, the description's main burden is explaining the incremental/paged search model — which it does via not_searched, the 20-notebook cap, and the status codes. The missing piece is routing guidance against the notebook read siblings.

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

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

There is a single required parameter with 100% schema description coverage ('Search text, case-insensitive'), so the schema already carries the semantics. The description adds nothing about matching behavior, multi-word handling, or result ranking, which lands this at the baseline 3.

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

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

The description states a specific verb and resource plus the search scope: 'Search notebooks: notebook names, page titles and page text.' An agent immediately knows this is a full-text search over notebook content, not a plain list. It does not, however, explicitly contrast itself with siblings like get_notebooks or get_notebook, so differentiation must be inferred.

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

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

Usage is implied rather than stated: the description explains the continuation protocol ('search again to continue') and references get_notebooks for the parent_done status, but never says when to reach for this tool versus get_notebooks/get_notebook. No exclusions or preconditions are given.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so safety is covered; the description goes well beyond by disclosing the Full Access Token requirement, the storage encoding (isStarred 3/2/1/-1), the account setting needed for Low/Toxic levels, and a concrete error contract (a permanent 500 means the task does not exist). This is exactly the extra context annotations cannot carry.

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

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

Purpose is front-loaded in the first sentence, and the remaining sentences carry auth, encoding, account-setting, scope-exclusion and error information, all of which earn their place. There is mild redundancy (priority is defined once as P1-P3/low and again as isStarred values), which keeps it short of a 5.

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

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

An output schema exists, so return values need no explanation. With three simple parameters, full schema coverage, and annotations covering the mutation profile, the description supplies everything else an agent needs: auth prerequisite, scope limits, the removal sentinel, account settings affecting visibility, and the failure signature.

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 by mapping the app-facing labels (P1-P3, low, dread levels 1-4) onto the integer encodings, including that 0 removes the setting. It is somewhat duplicative of the schema's own value documentation, keeping it just above 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?

States a specific verb (set/change) applied to a specific resource (priority and/or dread/frog level on a TASK), using the app's own vocabulary (P1-P3, low, isStarred, isFrogged). It explicitly distinguishes the target resource from projects, which use a different field and different 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?

Names when the tool applies (existing TASK) and when it does not (projects), and routes the caller to the correct alternative by name: update_category_or_project for project priority. The 'existing task' constraint and the wrong-ID failure mode further bound correct usage.

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

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

Annotations only declare the write/idempotent/safety profile; the description goes well beyond by disclosing the internal representation (task reminders list entry plus a type-M server entry), the cleanup behavior (mark_done/delete_task remove it), and a real operational constraint (standalone reminders require Marvin's mobile app for the notification). That is exactly the extra context annotations cannot express.

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

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

Front-loaded with the purpose, then the two modes in order. It is dense and includes some low-level implementation detail ('reminderId of 13 characters', 'type M') that is arguably noise for an agent, but it stays on one topic and every sentence carries routing or behavioral 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?

An output schema exists so return values need not be explained, and the annotations cover the safety profile. The description completes the picture with both invocation modes, the cleanup path, and the delivery limitation for standalone reminders, so an agent has everything needed 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?

Schema coverage is 100%, so the baseline is 3 and the schema already documents title/task_id/time_unix_seconds semantics. The description adds mode-dependent meaning beyond the schema, notably that standalone reminders need the mobile app for delivery, though most of the task_id/title split largely restates the schema text.

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

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

The description states a specific verb+resource ('Set a reminder') and immediately splits it into the two distinct modes it supports (on a task vs. standalone). It also names the sibling that handles the related clock-time case (update_task(time=...)), letting an agent distinguish it from update_task, get_reminders and delete_reminder without reading schemas.

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

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

It gives explicit conditional guidance: 'With task_id...' versus 'Without task_id...', and explicitly redirects the clock-time-on-a-task case to update_task(time=...). This is a clear when-to-use / when-to-use-something-else routing that leaves nothing 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 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 cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false) but the description adds substantial non-structured behavior: sets done=false and clears doneAt via /doc/update, refuses on projects/categories, day-removal semantics for firstScheduled 'unassigned', that the clock-time reminder is not restored, habit undo only fires if the last history entry matches habitRepAt, and that a permanent 500 means the document does not exist. This is well beyond what annotations 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 core purpose is front-loaded in the first sentence, and every subsequent sentence carries a distinct behavioral edge case, so the length is justified by the operation's complexity. The dense run-on structure makes it harder to scan than ideal, but there is little wasted text.

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

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

An output schema exists, so return values need not be explained, and the description still covers the tricky outcomes (refusal on projects, untouched habit on history mismatch, permanent 500). Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the schema description already states 'Task ID (not a project — those are reopened in the app)', so the description largely reinforces rather than adds new parameter syntax. It does add the downstream consequence of passing a project id, giving slight value 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+resource ('Undo a task's completion, and the habit's record') and immediately distinguishes itself from its inverse sibling mark_done and from record_habit. An agent can tell exactly what this does without opening the schema.

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

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

Explicitly routes alternatives: for an open habit task with a count it says nothing is written and to use record_habit undo=true instead; for reward points it points to unclaim_reward_points; for projects it says the call refuses and the app reopens it. When-to-use and when-to-use-something-else are both covered.

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 cover the safety/idempotency profile; the description goes much further by disclosing the hidden extra read call (1 extra API call) when project-only fields are supplied, the Full Access Token requirement, replacement semantics for note/label_ids, and the 500-instead-of-404 convention for missing IDs.

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

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

The core routing and blocking rules are front-loaded in the first two sentences, but the middle section is bloated with dated provenance notes ('live-tested 2026-09-11', 'verified 2026-08-29') and a philosophical justification for the category/project split that an agent does not need to invoke the 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?

Given 22 parameters and a mutation tool with only a bare annotation set, the description covers auth requirements, error semantics, cross-tool routing, refusal conditions, and strategy-dependent field behavior. With an output schema present, return values need no further 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 already 100%, so baseline is 3, but the description adds real meaning: which fields apply to categories versus projects, why day/due_date/priority/frog/size are refused on categories, and that label_ids works on both. A few parameters (orbit, no_auto_orbit, first_scheduled) are noted as undocumented, which is honest but leaves some residual ambiguity.

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

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

Opens with a specific verb+resource ('Update a category or project') and enumerates the editable surface. It explicitly routes task updates to update_task, so the agent can distinguish it from the closest sibling without opening either 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?

States when to use update_task instead, warns not to complete projects here because the app's side effects would be skipped, and explains the 'Projects ONLY' field blocking behavior on categories. It also gives explicit retry guidance for transient 500s versus permanent 500s.

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

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

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing read-modify-write semantics (section list read just before the write and rewritten in full), the exact side effect of removal (sectionId nulled on affected pages), and a stability caveat about undocumented experimental endpoints matched to app 1.71. This is exactly the extra context annotations cannot carry.

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

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

Front-loads the purpose, then layers constraints and mechanics efficiently in five short sentences with no filler. The endpoint/version sentence is dense but justified as a stability warning, so it 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?

An output schema exists, so return values need not be described, and the description covers the mutation semantics, refusal condition, side effects, and reliability caveat. An agent has everything needed to invoke this 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%, so the baseline is 3, but the description adds real semantics: the refusal condition constrains title, and the full-rewrite / null-out behavior explains how sections_add, sections_delete, and sections_rename interact. Only the id format and object shape are left entirely to 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: rename a notebook or change its sections, and scopes the rename to standalone notebooks. It does not name any sibling tool (e.g. update_notebook_page) to route the agent, but the standalone-vs-project distinction makes the operation 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?

Provides an explicit when-not: renaming is refused on a notebook that belongs to a project or category, with the rationale. It does not name alternative tools an agent should consider, so it stops short of full alternative routing.

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?

Adds a great deal beyond the annotations: overwrite-vs-append semantics, markdown rewriting ('- ' becomes '* '), immediate propagation to open clients, the section-not-following rule on move, auto-creation of a notebook when moving to a project/category, and the fact that the response signals parent-note re-pointing. It even discloses reliance on undocumented experimental write endpoints. Note the tension with destructiveHint=false (text replaces existing content) and idempotentHint=true (append is not idempotent), but the description itself discloses these behaviors rather than contradicting them, so the agent is not misled.

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

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

Front-loads the purpose and labels the move behavior, and the length is defensible for 8 parameters and several edge cases. A few clauses are dense and cryptic (e.g. the sentence about the response signalling an order change), which keeps it from a 5.

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

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

Given the parameter count, the move/section complexity, and an existing output schema (so return values need not be explained), the description covers the non-obvious edge cases well. It does not touch permissions/auth or error conditions, which is the remaining gap.

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

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

Schema description coverage is 100%, so the baseline is 3, but the prose genuinely adds meaning: it explains replace-vs-append behavior, the blank-line separator on append, the '- ' to '* ' rewrite, and that move_to_parent_id auto-creates a notebook. It clarifies semantics rather than merely restating 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?

Opens with a specific verb and resource plus an enumeration of the modifiable facets (text, title, order, section, move), which immediately distinguishes it from create_notebook_page and delete_notebook_page. An agent knows exactly which mutation surface this tool covers without opening the schema.

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

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

Gives strong contextual guidance on which parameter to reach for (text replaces vs append adds) and states conditional limits on moves ('the section does not follow', 'the first page of a notebook with a parent is not moved out'). It never names an alternative sibling or an explicit do-not-use case, so it stops just short of a 5.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, openWorld=false, so the bar is lower, yet the description adds genuinely non-obvious behavior: occurrences keep their old shape after a rule change, removal happens only with confirm=true, deleted occurrences linger in open clients until reload, custom accepts only an RRULE, and lowering create_occurrences via the API removes nothing while the app's dialog does. The occurrence removal it discloses for confirm=true is in slight tension with destructiveHint=false, but it is an explicit, opt-in cleanup of derived occurrences rather than destruction of the target task, so it is not scored as a contradiction.

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

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

The first sentence is a clean, front-loaded summary, but the rest is an unstructured ~230-word run-on that repeats 'via the API'/'in the app' and 'the app's dialog' many times and uses fragments like 'Mode list (default): they are listed...' to embed the confirm semantics. The density makes the critical list-vs-confirm rule hard to extract.

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 24-parameter update tool with an output schema present, the description concentrates on the surprising behaviors an agent most needs (occurrence reconciliation, confirm-gated deletion, delayed propagation, RRULE-only custom rules) while parameter-level details sit in a 100%-covered schema. It lacks only prerequisites such as permissions and what happens to untouched properties, so it is essentially complete.

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

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

With 100% schema description coverage the baseline is 3, but the description adds real semantics on top of the schema: changing repeat, interval or create_occurrences triggers reconciliation of open untouched occurrences from today on, custom accepts only an RRULE string, and lowering create_occurrences via the API removes nothing even at the next generation. These are behavior-level meanings the schema alone does not convey.

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

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

The opening line 'Change a recurring task: rule, window, place, end date, properties' gives a specific verb (change), the exact resource (recurring task) and the editable dimensions, so the purpose is unmistakable. It does not, however, differentiate itself from siblings such as update_task or create_recurring_task, so the agent must infer which tool owns 'recurring' semantics.

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

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

Usage is implied rather than stated: the 'Mode list (default)' vs 'confirm=true' discussion effectively describes a preview-then-confirm workflow, and the app-vs-API notes hint at when reconciliation happens. But there is no explicit 'use this tool when…' clause and no contrast against update_task/create_recurring_task, so an agent gets the mechanics of the confirm flag but not the selection rule.

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 non-read-only, idempotent, non-destructive; the description adds the endpoint and auth requirement (/doc/update, Full Access Token), the day/time coupling (T entry moves, own M reminders stay), the outcome of day='unassigned', and failure semantics (transient 500 retried once, permanent 500 = missing document). These are behavioral facts the 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?

Purpose and routing are front-loaded, and nearly every sentence carries a distinct behavior. Some lines are telegraphic to the point of opacity (the M/T entry shorthand, 'strategy-dependent fields are stored even when the strategy is off'), costing a little readability for a 29-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 high-complexity mutation tool it covers the essentials: auth level, destructive-free semantics, edge cases around scheduling and recurrences, and error transience. An output schema exists, so the description is not obligated to explain return values, and it correctly limits itself to noting reminders are echoed back.

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 cross-parameter meaning the per-field schema text cannot: changing the day relocates reminderTime and the T entry while own reminders remain, and subtasks are written with dotted keys. It stops short of documenting most of the 29 fields, which the schema already handles.

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

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

Opens with a specific verb+resource plus an enumeration of the updatable surface ('Update a task: title, day, time, reminders, size, subtasks'). It also routes three adjacent operations to their own tools (update_category_or_project, set_priority, mark_done), so an agent can distinguish it from siblings without opening any schema.

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

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

Gives explicit when-not guidance: categories/projects, priority/frog, and completion belong to other tools, and changes to a recurring task belong in update_recurring_task. The warning that parent_id/subtasks on a recurring occurrence leave the recurrence untouched is exactly the kind of exclusion that prevents a wrong call.

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