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?

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, and each parameter already has an explicit description, including an ISO 8601 example for start_iso and minimum constraints for length_minutes. The tool description adds no extra parameter-level detail, so the baseline 3 applies.

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

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

The description states a direct action ('Create') on a defined resource ('calendar event') and marks it as 'experimental.' It clearly distinguishes this from sibling tools like create_task and create_time_block by specifying the calendar-event context and external-calendar sync. No ambiguity remains about what the tool does.

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

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

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

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

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

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

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

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

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

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

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

For a tool that is a workaround with no official endpoint, the description is unusually complete: it explains the mechanism, auth requirement, id-handling behavior, downstream usage in task creation, and verification steps. Combined with the existing output schema and full param schema, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, with all four parameters (title, date, start_time, duration_minutes) already documented with formats and examples. The description adds no per-parameter detail beyond the schema, which is acceptable since the schema carries the burden. Baseline 3 is appropriate.

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the endpoint and return fields but provides little additional behavioral context such as authentication requirements or any caveats about tracking status. It is non-contradictory and adequate, but not rich.

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

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

A single, front-loaded sentence communicates the essential purpose, endpoint, and returned fields with no wasted words. It is concise without sacrificing clarity.

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

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

For a parameterless read-only endpoint with an output schema and annotations already present, the description is complete. An agent has enough information to select and invoke the tool correctly, and the output schema covers return-value details.

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

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

The tool has zero parameters, so the description has no parameter semantics to explain. Per the baseline for parameterless tools, a 4 is appropriate; the description adds useful detail about what data the response contains, which is helpful context beyond the empty schema.

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

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

The description names a clear verb+resource ('Get account info'), identifies the exact endpoint (/me), and enumerates the specific payload fields (email, tracking status, points balance). This makes the tool's purpose unambiguous and distinguishes it from the many sibling tools.

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

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

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

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

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

Annotations already mark this as read-only, and the description adds useful behavioral context: it returns the entire hierarchy, uses parentId='root' for the top level, and is meant for locating parent IDs. This goes beyond the annotations without contradicting them.

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

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

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

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

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

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

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics and correctly focuses on the return structure and usage purpose.

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

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

The description clearly identifies the resource (all categories and projects) and the operation (get as hierarchy with id and parentId). It is unambiguous and distinct from sibling tools like get_children or get_labels, though it does not explicitly name alternatives.

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

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

The description explicitly states a concrete use case: 'Use to find the right parent_id when creating/moving.' It gives clear context for when to call the tool, though it does not specify when not to use it or mention alternatives.

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

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

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

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

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

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

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

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

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

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

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

The input schema already provides complete parameter documentation (100% coverage) including valid values like 'unassigned' and 'root'. The description does not add new meaning to the parameter beyond what the schema states, so baseline 3 is appropriate.

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

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

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

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

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

Explicit guidance is given: call again for deeper levels, and for orphans, use get_today_items/get_due_items instead. This directly tells an agent when to use this tool and when to use alternatives.

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

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

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

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

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

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

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

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

Given the tool's complexity, the description is exceptionally complete. It covers source endpoint risk, date filtering semantics, caching, error handling with incomplete flags, excluded cases, sorting, and cost estimation. The presence of an output schema further reduces the need to explain return values, and the description covers everything an agent needs to invoke it safely.

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

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

Although the schema already documents both parameters, the description adds substantial meaning: it explains why lookback_days exists, that each day corresponds to one read call (~3.1s), and clarifies timezone interpretation. This elevates the semantics well beyond the bare schema descriptions.

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

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

The description opens with a specific verb and resource: 'Get tasks completed on a given date', which clearly identifies the tool's function. It further distinguishes itself with details like 'regardless of priority and deadline' and coverage disclaimers ('Tasks only — completed projects are not listed'), making it distinct from sibling list tools such as get_today_items and get_due_items.

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

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

The description provides strong contextual guidance on what the tool covers and its limitations, but it never explicitly names alternative sibling tools or states conditions for choosing this tool over them. The 'Not covered' section implies exclusions, but the absence of direct alternative routing keeps this at a minimum viable level.

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

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

Annotations already declare readOnlyHint=true, so the read-only 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?

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?

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?

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 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.