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

Annotations already declare the mutation profile (readOnly=false, destructive=false, idempotent=false), so the description is not required to repeat them. However, the description adds no behavioral context beyond annotation coverage: it does not mention tag auto-creation, duplicate-handling, permission needs, or side effects, leaving most behavior to be inferred from the 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 short sentences, front-loaded with the action and task types, with no wasted words. It is concise and easy to scan.

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?

Although an output schema exists and the input schema is rich, this is a complex 12-parameter mutation tool with nested scheduling and tag creation behavior. The description does not provide enough context for an agent to understand usage conditions, side effects, or task-type-specific constraints beyond what the schema already says.

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 92%, so the schema already documents nearly all parameters in detail. The description adds only a minor clarification that tags are given by name, and even that slightly conflicts with the schema's 'Tag names (or ids)' wording; baseline 3 is appropriate when the schema carries 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: create one of four Habitica task types. It clearly distinguishes creation from scoring/updating/deleting siblings, but does not explicitly contrast with them or mention the task resource in a broader sense.

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 habitica_update_task, habitica_score_task, or habitica_delete_task. It also omits prerequisites or conditions for creating each task type.

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

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

Annotations already flag destructiveHint=true, so the bar is lower, yet the description adds the non-obvious safety gate: the tool mutates nothing unless confirm=true. That is exactly the kind of behavior an agent cannot infer from the schema or 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?

Two sentences, front-loaded with the irreversible action and immediately followed by the required safety protocol. 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?

Output schema exists, so the preview's return shape needn't be spelled out; the destructive nature, the consent workflow, and the accept-forms of the task parameter are all covered.

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 nevertheless reinforces the meaning of confirm as a human-consent gate rather than a mere boolean switch, and pairs it with the preview 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?

States a specific verb and resource ('Permanently delete a task') plus the key qualifier of irreversibility, which separates it cleanly from habitica_update_task and habitica_score_task.

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

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

Gives an explicit two-step workflow: call without confirm to preview, show it to the user, then delete only on agreement. It does not name sibling alternatives for non-destructive edits, but the when/when-not condition is unambiguous.

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, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds useful behavioral context beyond that: it enumerates what the snapshot contains and flags edge-condition warnings such as a new day not yet started, though it says nothing about response size or limits.

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 content inventory comes first, followed by the routing advice. Every clause contributes either scope or usage direction.

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-required-parameter read tool with an output schema and full annotation coverage, the description supplies everything needed to call it correctly — what it returns, when to reach for it, and the warning semantics. No essential gap remains.

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

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

Schema description coverage is 100% and the single response_format parameter is fully documented in the schema, so the schema carries the burden. The description never mentions response_format or how verbosity affects the returned snapshot, adding no meaning beyond the structured field — 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 names a specific verb-resource pair (a snapshot of the user's Habitica day) and enumerates the contents: character stats, due dailies, to-dos, habits, and warnings. This clearly distinguishes it from siblings like habitica_list_tasks, which retrieve a single task category rather than an aggregated daily 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?

It gives explicit entry-point guidance — "Start here when the user asks what is pending or how they are doing" — which routes the agent ahead of the list/get siblings. It does not explicitly name an alternative or exclusion case, so it falls short of a full 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered and the bar is lower. The description adds that checklist items come back with ids (useful for follow-up habitica_manage_checklist calls) but says nothing about behavior when the task is not found, openWorld/lookup semantics, or whether tags are names or 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?

A single front-loaded sentence listing exactly what details are returned, with zero filler or repetition of the title.

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

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

With an output schema present, the description needn't explain return values, and the field enumeration plus annotations cover the essentials for a one-parameter read. The only missing piece is a failure/lookup behavior note (e.g., ambiguous partial text), which the schema partially handles.

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 already documents the id/alias/partial-text matching rule in detail, so the description adds no parameter meaning beyond it. Baseline 3 applies; the description does not compensate further nor detract.

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?

Specific verb+resource: retrieves full details of a single task, and the enumerated fields (notes, checklist items with ids, schedule, tags, dates) make clear it returns the complete object rather than a summary. This distinguishes it from habitica_list_tasks, which enumerates many tasks.

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

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

The word 'one task' implies single-record lookup and the sibling names (list_tasks, update_task) make the split reasonably inferrable, but the description never explicitly says when to use this versus listing tasks or when it is unnecessary. 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 already declare this as read-only, idempotent, non-destructive, and open-world. The description adds useful behavioral context by noting that each tag is returned with an active-task usage count, but it does not discuss ordering, whether inactive tasks are excluded from the count, or other retrieval behavior.

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

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

A single sentence, front-loaded with the action and resource, and it immediately adds the most useful scope detail. No wasted wording.

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 no-parameter read tool with rich annotations and an output schema, the description covers the essential purpose and the notable active-task count behavior. Minor gaps remain around count semantics and ordering, but nothing critical is missing for correct invocation.

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

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

The tool takes zero parameters, so the parameter semantics baseline is 4. The empty schema matches the description and leaves no parameter 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?

States a specific verb and resource ('List the user's tags') and adds scope detail ('how many active tasks use each one'), which distinguishes it from the mutation-oriented sibling habitica_manage_tags. It does not explicitly name that sibling, but the read-vs-manage split is clear from the tool name and description.

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 listing purpose implies when to use it, but there is no explicit guidance on when to prefer this over habitica_manage_tags or how it relates to tag creation/deletion. An agent can infer the use case, but the description provides no exclusions or 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?

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is fully covered structurally. The description adds the id-reuse workflow, but says nothing about the default 20-item cap, truncation, or cost of an unfiltered listing. Useful but thin beyond the annotations.

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

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

Two sentences with zero filler, and the primary action is front-loaded ahead of the filtering advice and the id-chaining hint.

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?

Six optional parameters, full schema descriptions and an output schema mean the description doesn't need to explain returns. It covers purpose and downstream id usage; only the truncation/limit behavior of an unfiltered listing is left unstated.

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

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

Schema description coverage is 83% and two enums (status, task_type) are documented inline with detailed semantics, so the schema carries the parameter burden. The description only gestures at 'filters' generically and adds no syntax, combination, or default behavior beyond that.

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 the user's tasks') plus the notion of filtering. It implies a collection-level read versus the single-task habitica_get_task sibling but never names that sibling, so differentiation is inferred rather than stated.

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?

'Prefer filters over listing everything' gives real selection guidance, and 'returned ids can be passed to the other habitica_* tools' describes the intended workflow into update/score/delete. It stops short of naming explicit alternatives or exclusions (e.g., use habitica_get_task when you already have an id).

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, idempotentHint=false and openWorldHint=true, so the low bar applies — yet the description adds little beyond them. It omits the confirm/preview safety behavior and the irreversibility of 'remove', and its return-value note is redundant with the existing output schema.

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

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

Two tight sentences, action scope first and return shape second, with zero 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, 100% schema coverage and full annotations, most structured needs are met. However, for a destructive mutation tool the description should at least signal that removal requires confirm/preview, which is an important behavioral fact an agent would benefit from seeing up front.

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 fully documents task resolution, item/text usage per action, and confirm. The description contributes no additional parameter meaning, which is the baseline 3 case.

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 pairs a specific verb set (add, rename, check/uncheck, remove) with a precise resource (checklist items of a daily or to-do) and states the return value. It is clearly distinguishable from siblings like habitica_update_task or habitica_delete_task, which operate on the task itself rather than its checklist.

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 four enumerated actions imply when the tool applies, but no sibling is named as an alternative (e.g. 'to edit task fields use habitica_update_task'). Exclusions and prerequisites are left implicit.

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, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description itself adds no behavioral context beyond the pointer to update_task – it does not mention the confirm/preview safeguard or that delete strips the tag from every task, both of which live only in the schema parameter descriptions.

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, zero filler, with the primary purpose front-loaded and the disambiguation second. Nothing to trim and nothing duplicated.

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, full parameter documentation, and destructive annotations, the description only needs to establish purpose and routing, which it does. It could go slightly further by flagging the irreversible two-step confirm flow at the top level, since an agent skimming only the description would not know a preview step exists.

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

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

Schema description coverage is 100%, including the confirm-preview semantics and the rename/delete vs create/rename mapping of tag and name, so the baseline of 3 applies. The description adds no parameter-level meaning beyond what the schema already states.

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

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

States specific verbs (create, rename, delete) against a specific resource (tag), and immediately clarifies the boundary with task tagging, which is the most likely source of confusion with siblings like habitica_update_task. An agent can pick this tool 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 names the alternative for the adjacent use case: 'To tag tasks use habitica_update_task(add_tags=...).' That is a concrete when-not-to-use-this rule plus a redirect to the correct sibling, which is exactly what usage guidance should do.

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 profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, but the description adds real context: scoring is reversible via 'undo', and buying a reward is a distinct purchase action. It also notes the response contains the character's post-scoring stats and a delta, which helps the agent understand the effect of a non-idempotent write. It does not mention permissions/authentication or what happens if the task text is ambiguous.

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, zero waste: the operation is front-loaded, followed by the return-value note. Everything 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 and the description still summarizes the return (stats + what changed), so return values are covered. The mutation/reversal semantics are conveyed for a non-idempotent tool. Minor gaps remain around failure modes (ambiguous task text, insufficient gold, already-completed tasks) that the agent would need to know.

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

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

Schema description coverage is 100% and the schema already defines direction's up/down meaning per task type and confirm's role in reward purchases. The description restates these mappings in prose without adding syntax, constraints, or edge-case detail beyond the schema, so 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 names a specific verb ('record progress') and enumerates exactly which operations it covers across the three Habitica task types (daily/to-do, habit, custom reward). This is clearly distinguishable from siblings such as habitica_create_task, habitica_update_task, or habitica_delete_task.

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

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

It states the contexts in which this tool applies (checking off, undoing, pressing +/- on a habit, buying a reward), which gives the agent a clear trigger. It does not explicitly name an alternative or exclusion (e.g., 'to edit task text use habitica_update_task'), so it falls 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 readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description adds the genuinely useful behavioral fact that omitted fields are untouched, which is the key safety/idempotency guarantee for a 13-param patch tool. It stays silent on side effects such as create_missing_tags defaulting to true and on schedule being replaced wholesale rather than merged, so it stops short of full disclosure.

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

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

Two clauses, zero filler: the partial-update rule is front-loaded and the alternative-routing sentence follows. 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 13-parameter mutation with a nested schedule object and an output schema, the description covers only the patch semantics and two sibling handoffs. It omits the tag-creation side effect and the replace-vs-merge behavior of schedule, both of which an agent must get right; the presence of an output schema excuses it from explaining return values, but not from these behavioral gaps.

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

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

Schema description coverage is 77%, so the schema already carries most parameter meaning (cost=rewards only, due_date=to-dos only, notes '' clears, schedule replaces the schedule). The description adds nothing parameter-specific, and the undocumented remainder (text, difficulty, create_missing_tags) is left entirely to the schema, so 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 ('Change fields of a task') and immediately clarifies the partial-update semantics ('only the given fields change'), which is exactly what separates it from create/delete siblings. It also names the siblings that handle adjacent operations (habitica_score_task, habitica_manage_checklist), so an agent can route correctly 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?

Explicitly routes two common adjacent intents away from this tool: checking a task off goes to habitica_score_task, checklist items go to habitica_manage_checklist. What's missing is guidance on the other obvious boundary (habitica_create_task / habitica_delete_task) and any precondition such as the task needing to exist or the ambiguity of a text match.

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