Aimgod

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

Annotations establish a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds the non-obvious ordering behavior: appended to the end, or at the top when the user chose 'New first'. That ordinal side effect is genuine extra context, though auth/permission needs go unmentioned.

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 action and scope, then the placement rule and style constraint. 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 small 3-param mutation tool with no output schema, the description covers where the item lands, its optional sphere/star, and the expected tone of the content. Only minor gaps remain, such as the 1000-character ceiling already carried by the 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?

The schema documents 'sphere' and 'important' but leaves 'text' bare, and the description compensates by framing it as the user's own short wording. It also maps the plain-language 'starred' onto the 'important' parameter and explains the sphere placement, adding meaning 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?

Specific verb+resource ('Add one focus point to the Focus section') that separates it from add_goal, add_task, and add_sphere. It states scope and optional modifiers clearly, though it doesn't name a sibling it is *not* to be confused with.

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

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

Gives a style instruction ('Keep it short, in the user's words') but no when-to-use/when-not guidance and no pointer to alternatives such as update_focus_point for editing an existing point or add_goal for goals. Usage is only implied.

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, openWorldHint=false), so safety is covered. The description adds useful defaults (date=today, horizon=month) but says nothing about duplicate handling, permissions, or response 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?

Two sentences, zero filler, with the core action and defaults front-loaded and the sibling routing placed at the end where it belongs.

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 7-parameter mutation tool with no output schema and 57% schema coverage, the description supplies defaults, the star/subgoal/after semantics, and the alternative tool. Only the sphere parameter and return behavior remain unaddressed, which is a minor 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?

With 57% schema coverage, the description compensates by explaining several parameters semantically: date defaults to today, horizon defaults to month, 'star' maps to the important flag, 'subgoals', and 'the goals it comes after' maps to the after array. Only sphere is left unexplained.

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 (add) and resource (one goal), and scopes it precisely to the month/quarter/year period containing date. It explicitly contrasts itself with the sibling build_goal_flow, so an agent can distinguish the two without opening either schema.

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

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

Names the alternative (build_goal_flow) and the condition that selects it ('for a whole path to a bigger goal'), and clarifies the default behaviors (date=today when omitted, horizon=month). It gives clear context but doesn't address other siblings like update_goal or delete_goal.

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

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

Annotations only cover the safety profile (non-read-only, non-destructive, closed-world). The description adds genuinely non-obvious behavior: duplicate names in the same sections are deduplicated and the existing sphere returned instead of a twin, plus the free-plan quota of 3 Planning spheres versus unlimited Goals/Focus. It does not describe the returned object shape, but the added semantics clearly exceed 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?

Three dense sentences, front-loaded with the create action and the section model. Each sentence carries new information (sections, default, dedup, quota), though the parenthetical glossary is slightly list-heavy.

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 3-parameter create tool with no output schema and only safety annotations, the description covers creation semantics, defaulting, deduplication, and quota limits. The only real omission is any hint of the returned sphere object (id, fields) an agent would need for follow-up calls.

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% (name undocumented, color and sections documented). The description supplies the section-to-purpose mapping and, more usefully, the default of 'planning' when sections is omitted, which is not encoded in the schema. The 'name' constraint (1-40 chars) is left to the schema, which is acceptable.

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 (Create) plus resource (sphere, defined as a 'life area'), with an explicit enumeration of the sections it can live in. This clearly separates it from add_goal, add_task, and add_focus_point, which operate on other entities.

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?

'Planning by default' tells the agent the fallback section when none is supplied, and the section list gives concrete usage context. It stops short of naming when not to use it (e.g., use update_sphere to modify an existing one, list_spheres to inspect), so it is clear but not fully 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 readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the new item sits under a task, but says nothing about permission requirements, whether the parent task is modified, ordering of inserted items, or limits on subtask count.

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 clear sentence, front-loaded with the action and the clarifying parenthetical, with no filler. It is efficient, though arguably terse given the undocumented parameters.

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 tool with annotations covering safety and no output schema, the description gives the minimum needed to understand intent. It falls short on parameter meaning and on distinguishing this tool from add_task, which are the remaining gaps an agent would need filled.

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% with two required parameters. The phrase 'under a task' weakly implies task_id identifies the parent task, but neither task_id's expected format nor title's constraints (1-200 chars) are conveyed in the description, so it does not compensate for the schema gap.

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 (add) plus resource (subtask) with a helpful gloss that 'subtask' means a checklist item, and 'under a task' states the containment relationship with the parent task. It is distinguishable from the sibling add_task, though it doesn't explicitly say how it differs.

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 tool is for creating checklist items beneath an existing task, which suggests a task must already exist. It never states when to use this instead of add_task, nor any prerequisites or exclusions, leaving the sibling routing ambiguous.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=false), so the description carries the rest and does so well: it discloses the date/time defaults, that reminders require a time, and that repeat spawns future-day tasks automatically rather than requiring repeated calls. It stops short of describing the return value or 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?

Three dense sentences with the defaults front-loaded and the highest-risk guidance (the repeat warning) last. Every clause carries information, though the final sentence is run-on and slightly harder to parse than 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?

For an 8-parameter create tool with no output schema, the description covers the parameters most likely to be misused (date, time, remind_minutes_before, repeat) and their interactions. The straightforward fields (title, sphere, starred, description) are left to the schema, which is reasonable and only a minor 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?

Beyond the 63% schema coverage, the description explains the defaulting behavior for date and time and the cross-parameter constraint that remind_minutes_before only works with a time, plus the semantics of repeat. It says nothing about sphere, starred, or description, which are the remaining undocumented parameters.

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 verb+resource are explicit ('Add a task to a day') and the description immediately scopes the operation with date/time defaults, so an agent knows exactly what is created. It never distinguishes itself from siblings like add_subtask or add_goal, but the resource naming is specific enough to be 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?

It gives concrete conditional behavior: no date means today, no time means the untimed list. For repeat it explicitly says one call is enough and warns 'never add the same task to several dates instead,' which is a genuine when/when-not rule. It does not point to alternative tools, so it stops 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 destructiveHint=true and openWorldHint=false, so the safety profile is partly covered. The description adds real value beyond that: it discloses that historical tasks and goals still reference the archived sphere, softening what 'destructive' means in practice, and imposes a user-intent gate. It stops short of saying whether archiving is reversible or how to restore.

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 compact sentence with the action front-loaded and the consequence and gating condition following. The clause 'past tasks and goals keep it' is slightly compressed/elliptical but still parseable; 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?

For a one-parameter mutation with full schema coverage and annotations carrying the safety profile, the description supplies the key behavioral nuance (history preserved) and the intent condition. Missing only reversibility/restore guidance, which is a minor gap for this simple 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?

Only one parameter, and schema coverage is 100% — the schema already documents that 'sphere' accepts a case-insensitive name or id. The description adds no format, matching, or ambiguity-resolution 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?

States a specific verb+resource ('Archive a sphere') and immediately clarifies the semantic scope: the sphere leaves every section but past tasks and goals retain it. This implicitly differentiates archiving from the deletion siblings (delete_goal, delete_task, delete_focus_point) by contrasting it with 'remove'.

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 gating condition — only archive when the user clearly asks to remove it — which is genuine when-to-use guidance rather than implied. It does not, however, name an alternative (e.g., update_sphere for renaming, or any restore path), so the guidance is clear but incomplete.

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 write (readOnlyHint=false) and non-destructive. The description adds real behavioral context beyond that: Aimgod places cards left to right, default horizon is month/today when omitted, and a hard cap of 12 goals. It does not disclose what the tool returns or how failures (e.g. exceeding limits) are reported.

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

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

Front-loads purpose before the structural rules, and every clause carries load (constraints, defaults, placement). The illustrative milestone example is slightly verbose but justifies itself by sharpening 'measurable'. Dense but not padded.

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

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

For a creation tool with no output schema and 3 params, the description is nearly complete: structure rules, limits, defaults, and ordering semantics are all covered. The main omission is not describing the return value (created goals' ids?), which matters for chaining into update_goal or link_goals.

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

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

With only 33% schema coverage, the description carries real weight and delivers: it explains `after` ('keys of goals in this flow, or ids already in the same period'), clarifies `final: true` and its 'nothing comes after' constraint, and covers the horizon default. It doesn't touch `sphere` or `important`, leaving those to the (sparse) 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 ('Set/Build') and resource ('a bigger goal and the path to it') and frames it as a one-step flow creation on the Goals canvas. This clearly distinguishes it from single-goal siblings like add_goal or link_goals, since it produces a whole structured flow.

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

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

Gives strong how-to-use guidance: exactly one final goal, 3-6 measurable milestones, 2-4 subgoals each, parallel branches, numbering that adds up. It sets clear expectations for correct usage. However, it never names an alternative tool (e.g. add_goal for a single goal) or an explicit when-not condition.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false. The description adds genuine context beyond them: the source goals are not deleted but remain 'in the archive, marked as moved', which resolves the apparent tension between the word 'move' and destructiveHint=false. It still omits idempotency (what happens if run twice) and any permission requirement.

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 with zero filler; the primary action is front-loaded and the secondary sentence answers the obvious follow-up question about the source goals.

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, annotated mutation tool with no output schema, the description covers the action, the scope, subgoal handling and the fate of the source goals. Minor omissions remain around default horizon, repeat-run behavior and the result of the call.

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

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

Schema description coverage is 0% and there is one parameter, so the description must carry the load. 'the previous month, quarter or year' maps directly onto the horizon enum values and conveys that the parameter selects the granularity of the source period. It does not state the default when horizon is omitted (required=0), leaving one gap.

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 (move) plus the exact resource (open goals of the previous month/quarter/year) and the scope (including open subgoals). No sibling tool performs a period-to-period carry-over, so it is unambiguously distinguished from add_goal/update_goal/list_goals.

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 by the phrase 'previous month, quarter or year', which suggests running it at the start of a new period. It never states when to prefer this over manually re-adding goals, nor any exclusions such as what happens when there are no open goals to carry.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds 'for good', which usefully emphasizes permanent deletion beyond the generic destructive flag, though it does not describe cascading effects or whether the operation can be undone.

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 followed immediately by the key usage constraint. No filler or redundant material.

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?

Annotations adequately cover the destructive nature of the operation, and the tool has only one required parameter. However, with no output schema and 0% schema description coverage for point_id, the description leaves the parameter underspecified and does not clarify return or side effects.

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% and the single required point_id parameter is never mentioned in the description. The target resource is named, so the need for an identifier is inferable, but the description adds no format, source, or usage detail for the parameter.

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 ('Delete a focus point'), and the verb alone distinguishes it from siblings such as add_focus_point, update_focus_point, and list_focus. 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 an explicit usage condition ('Only when the user clearly asks to delete it'), which is a clear when-to-use and implicitly a when-not-to-use guideline. It does not name alternative tools such as update_focus_point, but the context is clear enough for 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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds the non-obvious behavioral fact that deletion cascades to subgoals and arrows, which the annotations do not convey. 'For good' implies permanence but never states it as a hard, irreversible guarantee, so not 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, zero filler, with the destructive scope front-loaded before the usage caveat. Nothing repeats the title or 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 one-parameter destructive tool with annotations covering safety, the definition supplies the two things that matter: the cascade footprint and the caution bar. No output schema exists, so return-value detail is not owed; only the absence of any mention of dependent data recovery/irreversibility keeps it from 5.

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

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

Schema description coverage is 0%, so the schema carries only a name and uuid format for goal_id with no prose. The description adds nothing about the identifier, but a single, self-evident required UUID parameter is the mildest possible case, so this sits at the minimum-viable 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?

States a specific verb and resource ('Delete a goal') and immediately scopes the operation by naming what is destroyed alongside it ('its subgoals and arrows'). That cascade detail is what separates it from siblings like delete_subgoal, so an agent can route correctly without opening either schema.

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

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

'Only when the user clearly asks to delete it' is an explicit, conservative when-to-use guard — a meaningful constraint for a destructive tool. It does not name alternatives (e.g., update_goal or archiving) for a user who wants to remove but not destroy, so it falls short of the top band.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds 'for good' (permanence) and a confirmation requirement, but says nothing about cascade effects on the parent goal or behavior when the subgoal_id is invalid.

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 with the action and the guardrail front-loaded and no filler. The informal 'for good' is the only soft spot.

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

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

For a single-parameter delete with no output schema and annotations covering destructiveness, purpose and trigger are adequately covered. It still omits error behavior, parent-goal impact, and whether deletion is reversible, which an agent invoking an irreversible operation would want.

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% and the description says nothing about subgoal_id, so it adds no meaning beyond the schema's type/format. The parameter name is largely self-explanatory, which keeps this from a 1, but the low-coverage schema was not compensated for.

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

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

States a specific verb and resource ('Delete a goal's subgoal'), and the resource name itself separates it from the delete_goal/delete_task/delete_focus_point siblings. It is clear what is being removed, though it never explicitly contrasts itself with those 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?

'Only when the user clearly asks to delete it' gives an explicit trigger condition and guards against over-eager invocation, which is valuable for a destructive tool. It does not, however, mention alternatives such as update_subgoal or archive-style reversion when the intent is not hard deletion.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The phrase 'for good' usefully reinforces permanence/irreversibility, but the description says nothing about side effects such as whether subtasks are removed, or permission requirements. With annotations carrying the bulk, this is adequate but thin.

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 with no filler, and the destructive/permanent nature is front-loaded. 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 single-parameter destructive tool with annotations covering safety and no output schema, the description supplies the two things an agent most needs: permanence and the user-consent precondition. The remaining gap — cascade behavior toward subtasks — is a minor omission.

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

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

There is one required parameter (task_id) with 0% schema description coverage, so the description must compensate and does not — it never mentions the identifier or its format. The parameter is fairly self-evident from its name, but the description adds no meaning at all.

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

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

The description states a specific verb+resource ('Delete a task') that is unambiguous against siblings like add_task, update_task, and get_tasks. It does not explicitly name or differentiate itself from an alternative, but the operation is clear.

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

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

It gives an explicit precondition: 'Only when the user clearly asks to delete it.' That is real when-to-use guidance beyond the name. It stops short of naming alternatives (e.g., no soft-delete or archive option is mentioned), so it is not a full 5.

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

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

With readOnlyHint=true and openWorldHint=false already declaring a safe, local read, the description earns credit for disclosing return content that no output schema provides: streak target of 67 days, 8-week history window, 'weakest first' ordering, and that advice appears only 'if there is one'. It omits edge behavior such as what happens when task_id refers to a non-habit task.

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

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

Front-loaded with a one-line definition, then the two branches in a single dense sentence; no filler sentences. The second sentence is comma-heavy and long, which slightly hurts scanability, but every clause adds distinct return information.

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

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

For a read-only tool with no output schema, the description supplies the return contract the schema cannot. It is complete enough to call correctly in either mode. Minor gaps remain around very large habit lists and invalid task_id handling.

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 carry the parameter, and it does: task_id may be 'any day of the series', not just the start day, and its presence or absence switches the whole result shape. That is meaning beyond the bare string type. It stops short of format specifics (UUID vs id) or error conditions.

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?

It states the exact resource and what is returned in both modes: a habit's planned-vs-done over 4 weeks, streak toward 67 days, 8 weeks of history, verdict and suggestion, and month report; without a task_id, every live habit weakest-first. 'A habit is a repeating task' anchors the resource, making it distinguishable from the generic task tools. An agent knows exactly what this tool yields without opening a schema that has no descriptions anyway.

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 two modes are explicitly gated on task_id: 'With task_id (any day of the series)' versus 'Without task_id: every live habit'. This gives clear conditional guidance. It does not, however, say when to reach for get_habit instead of siblings like get_tasks or get_today, so sibling routing is left to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety bar is low, yet the description adds real behavior: shared-sphere tasks are included and carry specific extra fields (sphere, owner, my_role, locked, can_tick), and locked tasks are constrained to done/not-done via update_task. It does not mention ordering, pagination or response size for the 62-day case.

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 sentences, front-loaded with scope and defaults before the field-level and locked-task detail. The parenthetical field list is dense but each element carries actionable meaning; nothing is 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?

There is no output schema, so the description must carry return-shape burden, and it partially does by describing the 'shared' payload and 'ticked' semantics for owners/responsible people. The base task fields and pagination behavior are left to inference from sibling 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 coverage is 100% so both parameters are already documented with format and pattern, giving a baseline of 3. The description adds genuine meaning beyond the schema: an omitted date defaults to today and the pair of dates implies a maximum span of 62 days.

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 resource (tasks) and scope (one day, or a range up to 62 days via date/to_date), which is clear. It does not differentiate itself from the sibling get_today, which plausibly overlaps for the single-day case, so sibling differentiation is missing.

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 concrete operating guidance: omit date for today, the range cap of 62 days, and the rule that locked tasks may only be marked done via update_task and never renamed, moved, retimed or deleted. It stops short of naming alternatives such as get_today or list_goals for other retrieval needs.

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 return composition (date, goal, streak, tasks), which is useful since no output schema exists, but it omits any behavioral notes like aggregation or refresh semantics.

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 tight sentence that front-loads the resource and lists the payload without filler. Every clause earns its place, including the sibling pointer.

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 no output schema, the description must explain returns, and it does enumerate the fields an agent receives. Combined with read-only annotations, this is nearly complete, though it could clarify whether the result is a single aggregate snapshot vs. a list.

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 takes zero parameters, so there is nothing to clarify and the baseline of 4 applies. No syntax or format ambiguity exists for the agent to resolve.

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 resource (the user's 'today') and enumerates the specific payload: time-zone date, main goal, day streak, and today's tasks. It partially distinguishes itself from the sibling get_tasks by noting shared tasks are covered there, though it doesn't state a verb 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 pointer 'shared ones too, see get_tasks' implies a routing relationship to a sibling, but it doesn't state when to prefer this tool over get_tasks or get_habit, nor any exclusion conditions. Usage is only loosely implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the mutation/safety profile is covered. The description adds genuinely new behavior: directionality (first must be reached before the second opens), a same-period validation constraint, and a failure mode (loops are rejected). It stops short of saying what happens if the link already exists or on invalid 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 dense sentence front-loads the action and packs direction, precondition, and failure guard into few words. The 'draw an arrow' metaphor costs a little clarity but is compact and earns its place as the core mental model.

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 link tool with a self-explanatory title and no output schema, the description is adequate on semantics. It leaves gaps on parameter-level constraints, idempotency on repeat links, and error behavior, which matter more here because the schema supplies zero field descriptions.

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 two UUID fields are documented only by name. The description partially compensates by implying direction ('reach the first, then the second opens'), which maps onto from_goal_id/to_goal_id, but it never explicitly ties the ordinal language to the parameter names and omits that both IDs must reference goals of the same period - a constraint that directly affects parameter validity.

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 title gives a plain verb+resource ('Link two goals') and the description specifies the semantics: a directional dependency where reaching the first unlocks the second. It also distinguishes the constraint (same period) and the guard (loops refused). It does not name the sibling unlink_goals, but the purpose 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?

Usage is implied rather than stated - an agent can infer this is for building goal dependencies, and the 'same period' and 'loops are refused' clauses hint at preconditions. However, there is no explicit when-to-use vs when-not, and no routing to alternatives such as build_goal_flow or unlink_goals.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: result ordering (starred first, then the user's order), per-point position within a sphere, the 200-point page cap, and the presence of 'more'/'next_offset' fields. It does not disclose auth or rate-limit 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?

Three dense sentences with no filler: contents first, then filtering, then pagination. The most decision-relevant information is front-loaded and every clause carries an actionable fact.

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 no output schema, the description must carry return-value semantics, and it does for pagination ('more', 'next_offset') and ordering. It stops short of describing the shape of an individual focus point (identifier, text field), which an agent assembling follow-up calls to update_focus_point would benefit from.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: that omitting sphere returns all spheres, that the name match is against a sphere's list, and how offset ties to next_offset in practice. That is genuine added value on top of the schema text.

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

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

The description names a specific resource (the user's Focus section) and enumerates exactly what is returned: spheres with point counts and focus points with ordering and position. That is far more informative than a tautology, though it never explicitly contrasts itself with the similarly named siblings list_spheres or get_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?

It gives conditional usage for one parameter ('Pass sphere to see one sphere only') and a pagination loop ('when more is true, call again with offset set to next_offset'), but says nothing about when to prefer this tool over list_spheres or get_today, which share the sphere/point vocabulary.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the returned structure (subgoals with ids and done, arrows with after/leads_to, locked) and the non-obvious date behavior for resolving containing periods.

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 what is returned, then the horizon qualifier, then the date hint. Dense but every clause (subgoals, arrows, locked, date behavior) carries information; only the parenthetical notation is a bit telegraphic.

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?

There is no output schema, so the description must convey return contents, and it does list the key fields (subgoals, arrows, locked). Safety is covered by annotations. Missing only ordering/pagination/empty-result detail for a zero-required-param list 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 coverage is 50% (date documented, horizon not), so the description must carry some weight. It clarifies the horizon behavior (all three by default, or one) and explains what date does semantically, which is not derivable from the ISO pattern alone. Adequate but not rich.

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 the resource ('the user's goals') and the scope (month/quarter/year horizons) specifically enough to separate it from sibling readers like get_tasks or list_spheres. It lacks an explicit verb ('List') and does not name any sibling, but the resource and scope are 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?

'Pass date to see the periods that contain another day' and 'or only one horizon' imply when each parameter applies, giving implied usage context. However there is no explicit when-to-use guidance, no when-not-to-use, and no named alternative among the many sibling list_/get_ tools.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower; the description still adds useful context by disclosing the default scoping and the payload contents (colors and sections). It does not describe ordering or whether empty sections are returned.

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, no filler, with the default behavior front-loaded and the override option second. Every clause carries information.

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 lister with no output schema, the description adequately covers return contents and default scope. Minor gaps remain around ordering/pagination and the distinction from sibling list tools, but nothing blocking.

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 enum labels are already self-documenting, so the baseline is 3. The description's "Planning spheres (used by tasks)" adds a small hint about who consumes those spheres, but otherwise mirrors the schema text.

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

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

"The user's spheres (life areas) with their colors and sections" gives a clear resource plus what the payload contains, which separates it from list_goals/list_focus in the sibling set. It never names those siblings, so the differentiation is by implication rather than explicit routing.

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 default scope (planning, used by tasks) and tells the agent how to reach the other buckets ("pass section for Goals, Focus, Visualisations or all"), which is clear context for choosing a call. It stops short of saying when this is preferable to list_goals or list_focus.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description usefully adds that only the link is removed and 'the goals stay', which counters assumptions that a destructive arrow removal might delete entities. It says nothing about behavior when the link doesn't exist or about error cases.

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, operation stated first, and the clarifying constraint front-loaded immediately after. No filler and nothing redundant with 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?

For a two-UUID mutation with no output schema, the definition is minimally viable: the idempotent and destructive annotations cover safety, and 'the goals stay' clarifies scope. However, it omits what happens on a missing link, whether direction matters, and any reference to the inverse 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 0% and neither parameter has a description, so the description must carry the burden. 'From one goal to another' weakly implies directionality (from_goal_id → to_goal_id), but it never states that the two required UUIDs are source and target, nor that the arrow is directional.

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 ('Remove') and resource ('the arrow from one goal to another'), making the operation unambiguous. It does not name the sibling `link_goals` as its inverse, but the operation is still clear enough to be distinguished from add/delete/list 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?

There is no explicit when-to-use guidance, no prerequisites, and no reference to the obvious alternative (`link_goals`) or to `delete_goal` as the contrasting destructive-removal tool. Usage must be inferred purely from the name and the short purpose sentence.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral fact that omitted fields are left unchanged, but it does not disclose side effects such as reordering ("place") shifting the positions of other points in the sphere, which an agent would want to know before invoking.

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 waste: capabilities first, then the two operational essentials (partial update, id source). 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?

For a 5-parameter partial-update tool with no output schema and decent annotation coverage, the description covers all four updatable fields and the id source. It is nearly complete; only return/confirmation behavior and reordering side effects are unaddressed.

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

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

Schema description coverage is 80%, so the schema already documents place ("1 is the top"), sphere, point_id, and important. The description's restatement of those semantics is largely duplicative, leaving the baseline of 3 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 opens with a specific verb+resource ("Rename a focus point") and then enumerates every mutation the tool supports: star/unstar, move sphere, reorder. This clearly separates it from add_focus_point, delete_focus_point, and list_focus without the agent needing to open schemas.

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

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

"Send only what changes" gives explicit partial-update guidance, and "Point ids come from list_focus" routes the agent to the sibling that supplies the required point_id. It lacks any when-not guidance or prerequisites (e.g. permissions), but the operational context is clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. Beyond that, the description discloses two genuinely additive behaviors: that updates are partial ('send only what changes') and a dependency constraint on marking goals reached. It does not say what happens on invalid goal_id or how a removal (empty sphere) interacts with the non-destructive 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?

Three tight sentences, front-loaded with the operation list and followed by the two rules that matter (partial update, dependency precondition). No filler or 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?

With no output schema and a 6-parameter mutation tool, the description covers operations, update semantics, and one important business rule. It omits error/validation behavior and the effect of unsetting values, which are minor gaps rather than blockers 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 description coverage is only 33% (just sphere and important are documented inline), so the description must carry the load. It does: it maps text to rename, done to reached/not, important to the star, sphere to assignment, and add_subgoal to creating a child, giving meaning to parameters the schema leaves bare.

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 specific operations available (rename, mark reached/unreached, star, set sphere, add subgoal) against the 'goal' resource, so an agent knows exactly what can be mutated. It does not explicitly contrast itself with close siblings like update_subgoal or update_task beyond the resource noun, so it falls just short of full sibling 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?

Usage is implied through the partial-update instruction 'Send only what changes' and the conditional rule about marking a goal reached when it is preceded by linked goals in the same period. There is no explicit statement of when to prefer this tool over add_goal, delete_goal, or the update_* siblings.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the partial-update trait (send only changed fields), but says nothing about permission needs, reversibility, or whether renaming breaks existing references.

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, mutation targets front-loaded, with the operational hint ('send only what changes') in the closing clause. 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 4-param mutation tool with no output schema and annotations covering the safety profile, the description is nearly sufficient. The remaining gap is behavioral consequences of changes (e.g., whether altering sections discards existing content), which an agent might want to know before calling.

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 75% and both color and sections carry schema descriptions, so baseline is 3. The description maps plain-language verbs to parameters ('rename' -> name, 'color', 'sections it shows in') but adds no format or constraint detail beyond what the schema already supplies.

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

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

States a specific verb on a specific resource and enumerates the three mutable fields (name, color, sections). The resource 'sphere' clearly separates it from the update_task/update_goal/update_subgoal siblings, though it does not explicitly name a sibling to avoid.

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?

'Send only what changes' gives genuine patch-semantics guidance for a mutation call, which is more than nothing. However, it offers no when-to-use context against alternatives (add_sphere for creation, archive_sphere for removal) and no 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?

Annotations already declare this is a non-read-only, non-destructive, closed-world mutation. The description adds value beyond that by disclosing the lock-refusal behavior and the fact that subgoal ids are supplied with each goal, which is exactly the kind of operational detail annotations cannot convey. It does not cover what happens if both done and text are passed or neither, leaving a modest gap.

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 filler, and the core action is front-loaded before the id-sourcing and lock-precondition details. Every sentence carries information an agent needs.

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

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

For a small three-parameter mutation tool with no output schema and helpful annotations, the description covers the action, the id source, and the failure precondition. The only meaningful omission is guidance on the done/text interaction, which is minor given the schema's field names.

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 only 33% (just subgoal_id documented), so the description must compensate, and it does by mapping the two undocumented parameters to intent: done corresponds to ticking, text corresponds to renaming, and ids come from the goal's subgoals list. It still does not clarify whether done and text can be combined or whether at least one is required.

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 and resource ('tick a goal's subgoal done or not done, or rename it'), covering both mutation modes the tool supports. It clearly distinguishes itself from siblings like update_goal, delete_subgoal, and add_subtask without requiring the schema to be opened.

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 clear context for when the tool applies (ticking or renaming a subgoal) and states a real precondition: ticking is refused while the goal is locked. It stops short of naming an alternative tool or saying when not to use this one, so it is strong context but not full when/when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation safety profile is covered. 'Send only what changes' adds a partial-update contract, though the schema's single required field already implies the other fields are optional. Nothing is said about what happens to omitted fields or error behavior.

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

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

Two short sentences, front-loaded with the action and followed by the id prerequisite and update rule. 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?

There is no output schema, so return values need not be described. The description covers the actions, id source, and partial-update rule, but omits what a caller should expect on failure or how renaming interacts with existing title values, leaving minor gaps for a mutation 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 only 33% (just subtask_id), so the description must compensate. It does explain the semantics of the two undocumented parameters (done = tick, title = rename) and confirms id provenance, but adds no format, length, or clearing behavior 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 specific verbs (tick done/undone, rename) applied to a specific resource (subtask), and the tool name plus description clearly separate it from add_subtask and update_task. An agent can tell what it does without opening the schema.

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

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

It tells the agent where subtask ids come from (the subtasks list of a task in get_today or get_tasks), which is real prerequisite guidance and routes toward the sibling readers. It does not state any when-not condition or contrast against update_task, but the context is clear.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds substantial behavior the annotations cannot convey. It discloses null-as-removal for the reminder, the habit/statistics model behind repeating tasks, the 60-day-ahead materialization of repeat days, and the consequence of clearing a repeat (open days after today are deleted, done days remain) — real data-loss context. It also notes that a reminder change on a repeating task affects only that day.

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 correctly: the operation and its field list come first, conditional guidance second. Every sentence earns its place, though the final sentence is dense enough with parenthetical examples that it reads as two rules packed into one, slightly hurting scannability.

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 an 11-parameter mutation tool with no output schema, the description covers partial-update semantics, null-as-delete conventions, and the tricky habit side effects, which is the bulk of what an agent needs. It stops short of error behavior (invalid task_id), permission or shared-sphere authorization requirements, and what the call returns.

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 55%, so the description should carry more weight than a baseline 3. It names the fields that lack schema descriptions (done, starred, title, description) but adds no semantics beyond the names, and the two richest behaviors it explains (null removes the reminder; repeat clears future open days) are already spelled out in the schema. It compensates only partially for the coverage gap.

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

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

The opening clause gives a precise verb and resource ('Change a task') and then enumerates the mutable surface (title, date, time, done, starred, sphere, description, reminder, repeat), so an agent knows exactly what the tool touches. It does not explicitly differentiate itself from the sibling update_subtask or from add_task/delete_task, which keeps it 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?

'Send only what changes' states the partial-update contract that selects this tool over a replace-style update. The final sentence gives explicit when/when-not rules for repeating tasks: bulk moves ('move everything to tomorrow') must skip habits, a repeating task moves only when the user names it, and only to a day the habit lacks, with instructions to leave it and tell the user otherwise.

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