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

No annotations are provided, so the description carries the full burden. It does disclose a genuine behavioral rule — the nesting constraint that categories may only be parented by categories — but says nothing about permissions, name uniqueness, error behavior, or whether the parent must already exist.

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, zero waste, and the definition of the resource is front-loaded ahead of the constraint. Nothing is padded or repeated.

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 create tool with an output schema, the description covers what is created and the nesting rule. It omits defaults behavior (parent defaulting to root), whether titles must be unique, and what happens on an invalid parent — gaps that matter 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?

Schema coverage is 67%, with color ("#RRGGBB") and parent ("parent category id or name; 'root' = top level") documented in the schema but title left bare. The description reinforces the parent semantics via the nesting rule, but adds no syntax or format detail beyond the schema, 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?

Specific verb+resource ("Create a category") with a clarifying gloss ("a folder in the Master List") that defines the domain concept. It does not, however, differentiate itself from siblings like create_label or create_project, leaving the agent to infer the distinction.

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

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

There is no explicit when-to-use guidance and no mention of alternatives among the many create_* siblings. The one constraint given ("Categories can only live under categories") is a structural rule, not usage direction for choosing this tool over another.

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

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

With no annotations, the description carries the full burden; it does disclose the configuration prerequisite, which is genuine behavioral context an agent would otherwise miss. It says nothing about idempotency, duplicate-title handling, or what happens if the referenced group does not exist, leaving meaningful gaps for a mutation tool.

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

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

Two sentences, the action and scope are front-loaded, and the prerequisite is called out separately. Nothing is padded or redundant.

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

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

An output schema exists, so return values need not be explained, and the key gating prerequisite is stated. The remaining shortfall is the undocumented interaction between 'group' and 'new_group', which an agent needs to call this correctly.

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

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

Schema coverage is 80%, so the schema already documents color format, group identification, and new_group semantics. The description only restates the group nesting idea and adds no detail about mutual exclusivity between 'group' and 'new_group' or about 'new_group_exclusive'.

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

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

States a specific verb and resource ('Create a label') and adds the nesting scope (existing or new label group), so an agent knows exactly what is produced. It does not distinguish itself from the nearby create_category sibling, which handles a similar-sounding concept, 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 supplies a real precondition — the Task Labels strategy must be enabled in Marvin — which tells the agent when this tool will work. It offers no guidance on choosing between 'group' and 'new_group' or against alternative creation tools, so usage is only partly covered.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond the create action. It does not say where the project lands by default (parent defaults to 'inbox' only in the schema), whether creation is reversible, what happens to the source inbox item, or what errors are possible.

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 compact sentences with the core purpose front-loaded and no filler. The second sentence is terse to the point of being cryptic ('Convert an inbox item into one with this'), but nothing is wasted.

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

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

The output schema exists, so return values need not be described, but for a 7-parameter mutation tool with zero annotations and 29% schema coverage the description is far too thin. An agent lacks the parameter semantics and behavioral context needed to call it confidently.

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 only 29% (just 'parent' and 'priority' documented), so the description is expected to compensate and does not. It references the parent parameter only obliquely in the update_task workflow snippet and says nothing about note, labels, do_date, or due_date.

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

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

States a specific verb+resource ('Create a project') and adds the useful gloss '(container for tasks)' that distinguishes it conceptually from create_task. It does not, however, explicitly contrast itself with the sibling create_category, which is the closest ambiguous alternative.

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 one concrete usage path: converting an inbox item via this plus update_task(parent=…), which is real, actionable guidance. But it offers no when-not guidance and never mentions create_category or create_task as alternatives, leaving the agent to infer the boundary.

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

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

With no annotations at all, the description carries the full behavioral burden and discloses very little. It reveals that parent/label names are resolved server-side, but says nothing about permissions (even though schema fields like start_date/end_date say 'needs full access'), side effects, defaults (e.g. parent defaults to inbox), or failure modes.

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, front-loaded with the core action and followed by the one non-obvious constraint. No filler and nothing redundant with the schema.

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

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

For a 14-parameter creation tool with no annotations, this is thin. The presence of an output schema removes the need to explain return values, but the description never addresses permissions, default behavior, or the semantics of the numerous scheduling fields, leaving significant gaps for such a complex tool.

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 57% across 14 params, so the schema does much of the work (dates, importance scale, parent default). The description adds real value by clarifying that parent and label values are name-resolved and that shortcut syntax is rejected, which directly informs those two params, but it leaves the remaining undocumented params untouched.

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+resource ('Create a task'), which cleanly separates it from siblings like create_project, create_category, and create_label by resource type. It does not, however, explicitly differentiate from update_task or otherwise 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 only actionable guidance is the caution not to use '#/@' shortcuts, which is a syntax hint rather than a when-to-use rule. There is no statement of when to prefer this over update_task, create_project, or other ordering tools, and no prerequisites are given.

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

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

With no annotations, the description carries full behavioral burden. It signals this is a read-oriented session-bootstrap call ('call this once') and describes the shape of returned data, but it never states read-only semantics, performance/caching implications, or what happens if called repeatedly.

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 compact sentences with zero waste; the resource description comes first and the usage directive second, a natural front-loaded order.

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-argument query tool with an output schema that documents the return shape, the description supplies everything an agent needs: purpose, content, and session-timing. 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?

Zero parameters, so the baseline is 4; the description correctly implies no input filtering is needed and focuses entirely on return content.

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 the resource (category/project tree) and enumerates precisely what it contains: ids, open-task counts, labels by group, and strategies in use. It is clearly a structural-overview query, distinguishable from siblings like list_today or search_tasks, though it lacks an explicit verb and never contrasts itself with those siblings by name.

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?

Strong, specific timing guidance: 'Call this once at the start of a session,' plus the purpose of doing so ('it is how you map names to ids'). No alternatives or exclusions are named, which keeps it below 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?

No annotations are provided, so the description carries the behavioral burden alone. For a read-only fetch the safety profile is largely self-evident from 'get', and the description usefully discloses the payload shape and the task-vs-project branching. It does not state permission requirements, pagination, or behavior for a missing id, leaving some gaps.

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

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

One compact sentence with the core purpose front-loaded and the task/project branching handled parenthetically. Every clause carries information; nothing is 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?

An output schema exists, so the description need not document return values, and the sole parameter is fully documented in the schema. The description supplies the task-vs-project dual behavior, which is the main ambiguity for this tool. Only the absence of routing guidance versus sibling list/search tools keeps it from being fully complete.

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

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

A single parameter with 100% schema description coverage sets the baseline at 3. The description reinforces the schema by clarifying that the id may refer to either a task or a project, which affects the response shape, but adds no format or validation detail 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?

The description names a specific verb (get) and resource (task/project) and enumerates what 'full details' contains (note, subtasks, dates, tracking), which is far more informative than a bare restatement. It partially distinguishes itself from siblings like list_children by noting that a project returns 'its open children'. It stops short of explicitly contrasting with search_tasks or get_structure, so it lands at 4 rather than 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?

There is no explicit when-to-use guidance and no alternatives named. With siblings such as list_children, get_structure, and search_tasks in the same namespace, the agent must infer that get_task is the single-item detail fetch rather than a list/search tool. Usage is only implied, not 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?

With no annotations, the description carries the behavioral burden. It usefully discloses that only open tasks and sub-projects are returned and that traversal is non-recursive, but it omits pagination behavior tied to the limit parameter, ordering, and permission requirements.

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 definition is a single efficient sentence with the key scope information front-loaded. The parenthetical '(by id or name)' is compact and relevant, with no wasted words.

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

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

For a simple two-parameter list tool with an output schema, the description is nearly adequate: it states what is returned and the parent format. However, it leaves gaps around limit/pagination semantics and when to choose this tool over sibling listing or structure tools.

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 0%, so the description must document both parameters. It explains that the parent may be given by id or name, but says nothing about the limit parameter's role, default, or effect on output size.

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 clear verb-resource: lists open tasks and sub-projects directly inside a project/category. The scope 'directly inside' is specific, but it does not explicitly distinguish itself from siblings like get_structure or search_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 description implies when to use it (to see direct children of a project/category), but offers no explicit when-not conditions or alternative tools. No routing guidance against the many sibling list/search tools 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?

No annotations are provided, so the description carries the full disclosure burden. It usefully reveals that only open tasks are returned and that the default window is end of this week, but it says nothing about ordering, inclusion of overdue items, pagination, or how limit truncation behaves.

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

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

Front-loaded with the core semantics in the first line, followed by a compact Args block; no filler sentences. Slightly terse but 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?

An output schema exists, so return values need not be described. For a two-parameter filter tool the description is adequate, but it leaves ordering, overdue handling, and the limit default unstated, which are the details an agent would still need.

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 0%, so the description must compensate, and it largely does: it supplies the accepted value grammar for 'by' (YYYY-MM-DD plus relative keywords today/tomorrow/week/next-week/month) and explains 'limit' as the maximum number of tasks returned. It is missing only the default value for 'limit'.

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 (list) plus resource (open tasks) and the exact filter applied (Due date on or before a given day), which an agent can act on directly. It does not, however, distinguish itself from the sibling list_today, which overlaps heavily when by=today.

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

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

Usage is only implied: the 'on or before a day' phrasing tells the agent this is a deadline-window query, but there is no explicit statement of when to prefer it over list_today, search_tasks, or list_inbox, nor any exclusion conditions.

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?

No annotations are provided, so the description carries the full burden. It discloses ordering ('oldest first') and scope filtering, which are behavioral facts not derivable from the input schema. It does not mention sorting overrides, pagination behavior, or whether 'open' excludes completed tasks, but the coverage is solid for a lookup tool with an 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?

Single sentence, zero waste, and the scope constraint is front-loaded so the agent grasps the semantic boundary immediately. Every clause earns its place.

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

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

With an output schema present, the description needn't explain return values. It covers scope and ordering, which is nearly complete for a list-lookup tool. The minor gap is not explaining what 'open' means (e.g., excludes done tasks) or how limit interacts with ordering.

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?

Only one optional parameter (limit) and schema coverage is 0%, so the description should compensate but the parameter is largely self-explanatory. It adds the implicit default ordering context ('oldest first') that the limit applies to, though it doesn't explain the limit's behavior. Baseline 4 for a single-param tool is appropriate.

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

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

States a specific verb (list) and resource (Inbox tasks), and adds a precise scope constraint: not filed in any category/project. This distinguishes it from list_today, list_due, and search_tasks without needing to open a schema.

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

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

The 'not filed in any category/project' constraint implies when this tool applies versus other list_* tools, but it never names an alternative or states an explicit when-not-to-use. Usage is inferable but not spelled out.

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

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

With no annotations, the description carries the full burden, and it does disclose the non-obvious inclusion semantics — overdue-but-undone items are pulled in alongside same-day and due-by-then items. It says nothing about permissions or ordering, but the return shape is covered by the 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 compact lines with zero filler; scope rules come first, then the parameter format. Nothing redundant is included.

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 essentials are covered: what is included in the result set and how to format the day argument. The only gap is the unnamed resource and no cross-reference to list_due.

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 0%, so the description must compensate, and it does: it documents the accepted formats (YYYY-MM-DD plus the today/tomorrow/yesterday keywords), with the default visible in the schema. It adds meaning well beyond the bare 'string' type.

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 telegraphic phrasing "What's on for a day" implies listing items for a given day, and the three inclusion rules (do-date that day, overdue do-dates, due-by-then) define scope quite precisely. However, it never states the resource cleanly (tasks vs. anything else) and does not distinguish itself from the overlapping sibling list_due.

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

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

There is no when-to-use guidance and no mention of list_due, the sibling with the most obvious overlap (due items). The agent must infer that this is the day-scoped view and list_due the unfiltered one.

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

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

With no annotations, the description carries the full burden. It does add genuine behavior beyond the name — handling recurring/echo tasks and stopping tracking — which is useful context for a state-changing tool. However, it omits reversibility, permission needs, and what happens to subtasks or recurrence chains.

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 filler. The parenthetical efficiently packs the two key behavioral traits without bloating the definition.

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

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

An output schema exists, so return values need not be explained. But for a mutation tool with no annotations, the description leaves significant gaps around irreversibility and side effects on dependent items, leaving it only minimally complete.

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

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

Schema description coverage is 0% for the single item_id parameter, so the description must compensate. Saying 'a task or project' implies item_id accepts either entity type, which is real added meaning, but it doesn't specify ID format or restrictions.

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 ('Mark done') and resource ('a task or project'), with a clear side effect noted. It doesn't explicitly differentiate from siblings like update_task, which could plausibly also change status, but the purpose itself is 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 on when to prefer this over update_task or update_subtasks, and no stated prerequisites or exclusions. Usage is only inferable from the name, which is exactly the kind of inference a good definition should remove.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the AND-combination rule, that unset filters are ignored, and that done defaults to open-only. It says nothing about result ordering, the effect of limit/pagination, or whether unset boolean filters like frogged/backburner behave as 'ignore' vs 'false' – a real ambiguity for nullable booleans.

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 plus a compact set of quoted intents; the ANDing rule and ignore-unset rule are front-loaded. No filler, though the quoted examples are slightly redundant with one another.

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

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

An output schema exists, so return structure needn't be described, and the AND/unset semantics cover the query model adequately. For an 18-parameter tool with several undocumented filters and no pagination or ordering guidance, the definition is minimum-viable rather than complete.

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

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

18 parameters at 67% schema coverage sits between the 50% and 80% baselines, so the schema does most of the work. The description adds only the global AND/unset-filters rule, leaving undocumented params (frogged, backburner, has_due_date, has_estimate, limit, include_subprojects) unexplained in either place.

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?

Names a specific verb (Find) and resource (tasks) and states the core semantics (any combination of filters, all ANDed, unset ignored). It is clearly distinguishable from the sibling writers (create_task, update_task) and even implies it subsumes the narrower listers, though it never names list_today/list_due explicitly.

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 quoted example intents ('what can I do in 5 minutes', 'everything tagged X', 'scheduled this week in project Y') give concrete selection context and map naturally onto max_minutes, labels, scheduled_from/scheduled_to, and parent. However it gives no exclusions or explicit pointers to list_today / list_due / list_inbox when those narrower tools suffice.

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?

No annotations are provided, so the description carries the burden. It does disclose a meaningful behavioral trait: this is a state-changing force refresh that is 'normally automatic' (i.e., a manual override). It does not address whether local unsynced changes are overwritten, auth requirements, or rate limits, which matters for a mutation-style tool.

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

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

A single, front-loaded sentence that conveys the action, target, and the key qualifier (normally automatic) 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?

An output schema exists so return values need not be explained, and with no parameters the description is nearly complete. The main residual gap is not clarifying whether the forced refresh can discard local state, but for a zero-parameter sync trigger this is largely adequate.

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

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

There are zero parameters, so the baseline is 4. The description appropriately adds no parameter detail since none exist.

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 ('force-refresh') and resource ('the local mirror from Marvin'), making the operation immediately clear. It is distinguishable from the CRUD-oriented siblings, though it doesn't explicitly name or contrast with them.

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

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

The parenthetical '(normally automatic)' implies this is only needed when the user wants to override/force the default sync behavior, which suggests a usage context. However, it does not explicitly state when to invoke it vs. just waiting for the automatic sync, nor any prerequisites.

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

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

With no annotations, the description carries the burden. It discloses the required access level ('Requires full access') and that multiple mutation operations are supported, but does not explain side effects, irreversible removals, or conflict handling beyond the 'Requires full access' note.

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 waste. The first sentence front-loads the core purpose and operations; the second adds a critical prerequisite. Every word earns its place.

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

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

Given the tool's complexity (6 parameters, multiple operations) and the presence of an output schema, the description covers the main operations and the key access requirement. It could add a note about return behavior or error cases, but with the output schema present, this is largely sufficient.

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%, so the schema already documents most parameters. The description adds no parameter-level detail beyond the operation names, which are already reflected in the parameter names and schema descriptions. 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 ('Add, complete, reopen, rename or remove') and resource ('subtasks of a task'), enumerating all mutation operations. This clearly distinguishes it from siblings like update_task or mark_done.

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

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

It provides some context ('subtasks of a task') and a prerequisite ('Requires full access'), but does not explicitly state when to use this tool versus alternatives like update_task or mark_done, nor when not 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?

With no annotations, the description carries the full burden and does disclose two non-obvious traits: only the passed arguments are mutated (patch semantics, not replace), and a full-access token is required. It omits anything about the destructive 'clear' path, reversibility, or rate limits, keeping it below a 5.

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

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

Two short sentences, front-loaded with purpose and followed immediately by the two constraints that matter most. Every clause earns its place; nothing is padding.

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

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

For a 20-parameter mutation tool, an output schema exists so return values need no explanation, and the description supplies the overview plus patch semantics and auth needs. The main residual gap is that destructive behaviors (clearing dates/notes via 'clear') are not flagged in the description, though the schema covers them.

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 65%, and the description adds a useful conceptual mapping (rename→title, move→parent, relabel→labels, schedule→dates, deadlines→due_date, estimate→estimate_minutes, note→note). However it adds no syntax, format, or interaction detail beyond what the schema already documents for those fields, so it only marginally compensates for the uncovered parameters (frog, backburner, add/remove_labels, review_date).

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 (Edit) plus the resource (task or project) and enumerates the editable facets: rename, move, relabel, (re)schedule, deadlines, estimate, note. An agent can distinguish this from create_task, mark_done, and create_project. It does not explicitly differentiate itself from update_subtasks, 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?

Usage is implied rather than stated: it's the tool for modifying an existing task or project. There is no explicit when-not guidance and no routing to siblings such as update_subtasks for child items or mark_done for completion. The partial-update rule and token requirement give some operational context but not selection criteria.

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