AimYear

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

Annotations already declare that this is a non-read-only, non-destructive, idempotent, closed-world operation. The description adds useful context about what registration enables (server reminders) and why the tool exists outside the normal self-registration flow.

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

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

The description is two tightly written sentences with the core action and usage context front-loaded. There is no redundant or filler text.

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

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

For a simple three-parameter registration tool with annotations covering safety and idempotency, the description is mostly complete for selection and basic invocation. The main remaining gap is parameter-level guidance for token, platform, and label.

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 should compensate for three undocumented parameters. It mentions the device token conceptually but does not explain token format/minLength, the platform enum, or the optional label 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 gives a specific verb and resource: "Register a device token," and explains its purpose in terms of server reminders. It also distinguishes the normal phone-app self-registration path from the testing/manual use case.

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

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

It clearly says when this tool is intended: testing or manual token registration, compared with the phone app registering itself. It does not explicitly mention alternatives such as list_devices or delete_device, but the main usage 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 a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds real behavior beyond that: the move counts toward the weekly target, setting completes_item ticks the linked plan item and its path step, and past dates are accepted. It stops short of saying what is returned or what happens if a referenced itemId does not exist, which keeps it off 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?

The core definition and the sibling routing are front-loaded, and every clause carries information. It is dense with stacked parentheticals ("Classified like a session (pass leverId, stepId, itemId or projectId when known)"), so it reads as crammed rather than elegantly structured, but nothing is truly expendable.

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 9-parameter mutation with no output schema, the description covers the required field, the optional date backfill, the link parameters, and the completes_item side effect. What remains undocumented is the time and area parameters (both described in the schema) and any error behavior for unknown ids, a small residual 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 78% schema coverage the baseline is 3, and the description earns above it: it explains task as "what changed, in plain words," clarifies date may be a past day, and supplies classification guidance for leverId, stepId, itemId and projectId, two of which have no schema description at all. Minor friction: it refers to "item_id" where the parameter is named itemId.

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?

"Record a move: one action toward the aim with no duration" gives a specific verb plus a precise definition of the resource, and the examples (small fix described from the phone, message sent) bound what counts. It explicitly contrasts with add_session, so an agent can separate it from the closest sibling without opening a schema.

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

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

The final sentence names the alternative and the selecting condition: "Use it for work that had no timer; use add_session for timed work." It also pre-authorizes backfilling ("Past days are fine (date)") and states the completes_item condition, leaving little 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral content: the note is one-line, and the call may have the side effect of classifying a previously unclassified session — a non-obvious consequence an agent should know.

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, front-loaded with the action and immediately followed by the target scoping and the side-effect caveat. Minimal waste, though the parenthetical scoping phrase interrupts the flow slightly.

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 mutation tool with annotations covering safety and a schema documenting the two optional params, the description is adequate but leaves gaps: it says nothing about the effect on the session's state beyond classification, failure behavior, or whether the note persists. No output schema exists, so return behavior is also 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 coverage is 67%: op_id and session_id carry detailed schema descriptions (including the replay/idempotency semantics), so the description only needs to compensate for the undocumented note param. It does so partially by saying "one-line" and clarifying which session is targeted by default, but adds no format or length 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?

States a specific verb+resource ("Add a one-line note to a running session") and scopes the target to this connection or a session_id. It is clearly distinguishable from siblings like add_steps or add_session, though it doesn't contrast itself with them 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 parenthetical "this connection's, or session_id" implies the default target, which is helpful, but there is no explicit when-to-use/when-not guidance or named alternative among the ~40 sibling tools. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds important behavior beyond those hints: posts go to settings-selected or explicitly given networks, networks where the user already posted are skipped, and a retry never posts twice. It also discloses the today/yesterday limit and the Pro 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?

The description is a tight, front-loaded paragraph with no wasted sentences. The safety condition appears immediately after the action, and the remaining constraints are packed into a few efficient clauses.

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 write tool with no output schema, the description covers the key invocation context: explicit user confirmation, draft defaulting, network selection, skip behavior, idempotency, and date limits. It does not describe return values or failure/partial-success behavior, and “Pro” is left unexplained, but overall it is complete enough to call 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 67%, so the description must add meaning for the under-documented parameters. It does: text defaults to the draft from get_post_draft and is the user-edited draft, date is limited to today or yesterday, and networks defaults to settings but can be overridden. It could still be slightly more explicit about how networks interacts with settings, but it meaningfully supplements 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?

The description states a specific verb and resource: posting the day's progress to social networks. It distinguishes this from the sibling get_post_draft by explaining that text defaults to the draft from that tool, so an agent can tell the two apart 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?

It gives an explicit precondition: only after the user explicitly said to post. It also names the draft source, the date window (today or yesterday only), and the network-selection behavior. These are clear when-to-use and constraint rules, with get_post_draft implied as the preceding step.

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

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

With annotations only declaring the write/safety profile, the description adds real behavioral context: how time is entered (minutes ending now or at end, or start+end), and the op_id replay mechanism that makes a retry apply once. That is a meaningful disclosure beyond idempotentHint=false, and it does not contradict 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 core action and input modes, then use cases, then the retry caveat. No filler, and the most consequential instruction (op_id) is placed last where it is easy to act on.

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

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

For a 13-parameter mutation tool with no output schema, the description covers the essential input modes and the idempotency contract. It leaves the relationship of secondary fields (area, weight, exclusive, ids) to the schema, which mostly documents them, so the remaining gap is small.

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 69%, so several parameters (task, leverId, projectId) carry no description. The description compensates by explaining the two input modes for minutes/start/end and the exact contract of op_id ('do not invent one; an agent calling interactively leaves it out'), which is the most error-prone 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?

States a specific verb (add) and resource (past time/session) and qualifies it as 'time that was not timed', which cleanly separates it from live-timing siblings like start_session and stop_session. It never names those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

Gives concrete use-case context — calls, children, workout, paid work, or work away from the agent — which tells the agent when this tool applies. It also explains the queued-app replay scenario for op_id, but does not explicitly name alternatives (e.g. edit_session) or state 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?

Annotations already declare idempotent, non-destructive, open-world behavior. The description adds meaningful context beyond them: credentials are validated against the login, stored encrypted, and never shown again, and the Bluesky account password must never be used instead of an app password.

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

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

Purpose is front-loaded, and every sentence carries useful information about either credentials or handling. The credential breakdown makes it slightly dense, but no sentence 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 4-parameter tool with annotations but no output schema, the description covers credential sourcing, security handling, and the primary invocation path. It does not describe behavior when the account is already connected or when validation fails, 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?

Schema coverage is 75%, so a baseline of 3 applies, but the description adds value: it explains where the WIP api_key comes from (wip.co settings), how to obtain a Bluesky app password (Settings → Privacy and security → App passwords), and explicitly forbids using the account password.

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 (connect) and resources (WIP and Bluesky social accounts), plus the downstream purpose (AimYear posting daily progress). An agent can distinguish this from list_social_accounts or delete_social_account without opening any schema.

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

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

Gives clear usage context: the app's connect screen normally calls this, and if a key is pasted into chat it should be used once and not repeated. It does not name alternatives or exclusions, but there is little ambiguity about when to call this.

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 write/non-idempotent/non-destructive profile, and the description adds real behavioral context beyond that: input is validated ('abstract steps are rejected') and ordering violations produce a warning ('warns otherwise'). It stops short of naming the failure mode or the response shape.

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

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

Front-loads the action, then layers the acceptance rule and ordering rule compactly. Every sentence carries content, though the trailing 'warns otherwise' is clipped enough to be slightly ambiguous.

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-param mutation tool with no output schema and no documented return value, the description covers validation and ordering but omits prerequisites, what the call returns (created step ids?), and how partial failures in a multi-step array are handled.

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% (only op_id is documented), so the description must compensate. It conveys domain meaning for steps (concrete, work-block-sized, lever ordering) but never maps to the actual fields milestoneId, title, leverId, or estimateMin. Partial conceptual coverage only.

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 ('Add concrete steps to a milestone') and immediately qualifies what a valid step is versus an invalid one ('email 10 people from the waitlist', not 'do marketing'). An agent can distinguish this from edit_step/delete_step/next_steps from the description alone.

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 in-tool guidance (abstract steps are rejected; hard-lever step first; preparation only where it blocks) but never says when to choose this over a sibling like edit_step or when not to call it. Usage context is implied rather than explicit.

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 (readOnly/idempotent/non-destructive), so 'Changes nothing' is largely reinforcing structured data. However, the description goes beyond annotations by disclosing the return contract ('Returns problems[] and next_question') and the iteration semantics of the loop-until-clean workflow, which no output schema supplies.

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

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

Front-loaded with the core action and free of filler; every sentence carries purpose, workflow, or parameter guidance. The packed parenthetical rubric and semicolon chains make it dense to parse, which is the only thing keeping it from a 5.

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

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

No output schema exists, yet the description supplies the return shape (problems[], next_question), the validation criteria, and the downstream step (set_goal). For a validation tool with six params, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 67%, and the description adds meaning past the schema: it maps metric/baseline/target onto the rubric ('a countable metric with value today and target'), states the 'deadline within 12 months' validation rule, and explains the count-vs-done tradeoff that the enum alone doesn't 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?

States a specific verb and resource — 'Check a goal that is not saved yet against the rubric' — and pins down scope (draft, unsaved) that distinguishes it from get_goal and set_goal. An agent can tell exactly which object this operates on without opening the schema.

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

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

Explicitly routes the agent: 'loop until problems is empty, then call set_goal' names the alternative and the condition that selects it. The tie-breaker 'Prefer count; use done only when no honest number exists' resolves the enum choice in ambiguous cases.

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=false, so the safety profile is partly covered. The description still adds real value beyond them: it specifies exactly what is destroyed (the sign-in), the immediate consequence (cannot read or change anything), and the reversibility nuance ('until it connects again'), which counters the assumption that a delete is permanent.

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: effect first, then the usage constraint, then parameter sourcing. Every sentence earns its place and nothing is redundant with the title or annotations.

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 tool with no output schema, the description covers what happens, when to call, and where to get the parameter — enough to invoke it correctly. It does not address what is returned or how failures (invalid/already-deleted client_id) surface, which would complete the picture.

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 single required client_id would otherwise be undocumented. The description supplies its provenance ('from list_agents'), which is genuinely useful for discovery, but nothing about format, length limits, or behavior on an unknown/already-revoked client_id. That is adequate but leaves a real gap for a 0%-coverage 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?

States a specific verb and resource ('delete_agent' / 'Disconnect one agent') and immediately defines the scope of the effect: the sign-in is deleted and it can no longer read or change anything. This clearly distinguishes it from list_agents and from other delete_* siblings, which target different resources.

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 on the user's explicit request' gives a clear precondition for calling and effectively acts as a when-to-use guardrail for a destructive operation. It does not name an alternative (e.g., a revoke/pause action) or a when-not case beyond the explicit-request bar, so it falls short of score 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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — reminders stop — but says nothing about auth requirements or whether removal is reversible. With annotations carrying the core disclosure, a 3 fits.

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

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

One short sentence, front-loaded with the verb and resource, zero filler. It is efficient, though the very brevity is part of why parameter and usage detail are absent.

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 destructive delete whose annotations already cover safety, the description conveys the action and its effect, so an agent can proceed. The gap is the undocumented token parameter and absent guidance on alternatives; no output schema exists, so return values need not be explained.

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 single 'token' parameter has 0% schema description coverage, and the description never mentions how the device is identified or what form the token takes. For a 1-param tool where the schema does no explanatory work, the description should compensate but does not.

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 concrete verb and resource ('Remove a device') and adds the observable consequence ('stops receiving reminders'), which distinguishes it from add_device, list_devices, and the delete_session/delete_step siblings. It does not explicitly name a sibling, but the resource 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 when-to-use, when-not-to-use, or alternatives are given. Nothing tells the agent that list_devices or add_device are complements, or under what conditions deleting (vs. disabling) a device is appropriate.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the side effect that a ticked plan item remains ticked after deletion. It does not say whether deletion is permanent or recoverable, which is left to the 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 short sentences, front-loaded with the action and immediately followed by the operational detail and the side-effect caveat. Every sentence earns its place with no filler.

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

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

For a one-parameter destructive delete with annotations covering safety and no output schema, the description supplies the essential operational facts: what to delete, where the ID comes from, and what side effect does not occur. Only minor gaps remain, such as permanence of the deletion and behavior on an unknown move_id.

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 single move_id parameter has 0% schema description coverage, so the schema carries no meaning. The description partially compensates by stating the value comes from list_moves, giving provenance but not format, type constraints, or error behavior for invalid IDs.

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 move") and narrows scope with "recorded by mistake." The clause "A plan item it ticked stays ticked" implicitly distinguishes it from delete_plan_item, though it never names that sibling directly.

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

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

Gives a clear usage context (correcting an accidentally logged move) and tells the agent where to obtain the required ID via list_moves. It stops short of explicit when-not guidance or naming delete_plan_item as the alternative for a different removal need.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotency, so the safety profile is covered. The description adds genuine value with 'A routine item is skipped for that day only,' clarifying that a routine occurrence is a temporary exception rather than a permanent deletion. It does not say whether non-routine items are removed permanently or whether the change is reversible.

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 core action, and the second sentence carries non-redundant scope information about routine items. 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 destructive, non-idempotent mutation with no output schema, the description is thin: it does not state what the response is, whether removal is permanent, or how to re-add the item. Annotations cover the safety signal, but the agent lacks enough context on the non-routine deletion path.

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 50%: 'date' is documented with its format and timezone in the schema, but 'itemId' is undocumented in both schema and description. The description alludes to 'one item' and 'a day's plan' but adds no syntax, sourcing, or meaning beyond that, leaving the required parameter's semantics 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 ('Remove') and resource ('one item from a day's plan'), which is clear and scoped. It does not explicitly distinguish itself from the close sibling edit_plan_item or set_plan, so an agent must infer the boundary from names alone.

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 when-to-use guidance, no prerequisites, and no named alternative (e.g., edit_plan_item for modifying rather than removing, or set_plan for bulk changes). The only guidance is the indirect semantics of skipping a routine, which is behavioral rather than usage-oriented.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the fallback only ever targets this connection's own running session and never another session's, which bounds the blast radius in a way the annotations do not.

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 padding, and the primary action is front-loaded ahead of the parameter guidance. Every clause carries operational 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 two-parameter destructive tool whose annotations carry the safety profile and whose schema documents both params, the description covers the remaining gaps: deletion scope, parameter sourcing, and default target. No output schema exists, so return values need not be explained.

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

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining where session_id comes from and what happens when it is absent. The op_id semantics are fully handled in the schema itself, so no further description is needed.

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 session) plus an explicit scope: running or finished. The phrase "so it no longer counts" separates it from the adjacent stop_session/edit_session siblings, which imply halting or modifying rather than removing.

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 guidance: pass session_id sourced from get_now or list_sessions, and states the default behavior when it is omitted (only this connection's single running session). It does not explicitly contrast with stop_session when a running session should be halted instead of deleted, so usage context is clear but not complete.

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=false. The description adds real value beyond that by specifying exactly what is destroyed (the saved login) and what survives (existing posts). It does not address reversibility, permissions, or effects on drafts/scheduled content, so a 4 rather than 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 action stated first and the retention caveat immediately after.

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 full annotation coverage, the description covers purpose, scope of deletion, and a key data-retention caveat. Minor gaps around reversibility and permissions keep 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?

Only one parameter exists and schema description coverage is 0%, so the description carries the burden. It mentions 'a network' but never explains the wip/bluesky enum values or the expected input format; the self-explanatory enum in the schema does most of the work.

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: 'Disconnect a network and delete its saved login.' It also delimits scope by noting posts already made are retained, which cleanly separates it from add_social_account and list_social_accounts.

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 disconnect framing makes the use case clear (removing a connected network), and the sibling set makes add_social_account the obvious inverse. It never explicitly says when not to use it or names an alternative, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that — it does not say whether the delete is permanent, whether the path is renumbered, or what happens to dependent steps. Not contradictory, but no incremental value.

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 wasted words, but its brevity comes at the cost of under-specification rather than genuine economy.

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

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

For a destructive mutation with no output schema and undocumented parameters, the description omits reversibility, side effects on the surrounding path, and error behavior. It is too thin to fully equip an agent to invoke it correctly.

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

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

With one required parameter at 0% schema description coverage, the description carries the burden; it only implies the single-step target ('one step') without explaining what stepId is, its format, or where to obtain it.

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

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

States a specific verb (delete) and resource (step) with scope ('one step from the path'), which clearly separates it from delete_device, delete_plan_item, and delete_session. It does not explicitly name an alternative or contrast with sibling tools like edit_step, 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?

There is no guidance on when to delete a step versus editing it (edit_step) or restructuring via add_steps/split_attention. No prerequisites, permissions, or ordering caveats are 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?

Goes well beyond the annotations (which only cover idempotency and non-destructiveness) by disclosing real side effects: status=retired drops the milestone without finishing, and done/retired advances its track to the next milestone. It also reassures that steps are preserved, which an agent would otherwise have to guess.

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 dense sentences, front-loaded with the scope and followed by the highest-value behavioral caveats. No filler and no restatement of the title.

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

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

For a non-readonly mutation with no output schema, the description covers the state transitions an agent most needs to avoid surprises. It does not say what the response contains or whether partial updates are returned, a minor omission given annotations carry the safety profile.

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 38%, so the description must compensate, and it does by enumerating every editable field (title, kind, metric, target, due, status, track) and adding the status=retired semantics the schema lacks. Gaps remain around target/metric interaction, which the schema's kind note only partially covers.

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 ('Change') and resource ('one milestone') and enumerates the editable fields, so it reads clearly against the plural sibling set_milestones. It never names that sibling explicitly, so sibling differentiation is implied rather than stated.

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

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

The single-milestone framing implies this edits an existing milestone rather than creating one, and the status notes hint at lifecycle usage. However, there is no explicit 'use this instead of set_milestones when...' guidance or statement of prerequisites, so selection between siblings 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 readOnly=false, idempotent=true, and destructive=false, so the safety profile is covered. The description adds genuine cross-entity behavior that annotations cannot convey: done=true also completes the linked path step, and count>0 ticks while 0 unticks. It stops short of describing permission requirements or full side-effect scope.

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 sentence structure is front-loaded, starting with the core verb+resource before drilling into per-parameter semantics. For a 12-parameter tool, the length is defensible, though the routine/'bad-day minimum' clause is dense and slightly redundant with the schema enum.

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 annotations covering safety and no output schema to explain, the remaining burden is on documenting the 12 parameters and the linked-entity model. The description handles the done/count/level semantics but omits how the linking parameters (stepId, leverId, projectId, date) relate to the plan item, leaving an agent to guess at a non-trivial mutation surface.

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 25%, so the description must carry more weight. It explains done, count ('how many units this tick did'), and level ('counts for the day, reported apart from full') well, but leaves itemId, stepId, leverId, projectId, date, and isMainStep undocumented in both schema and prose. It clarifies the highest-value parameters but does not fully compensate 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 description opens with a specific verb ('Change') and resource ('one plan item') and enumerates the editable aspects (done status, title, estimate, area, links, main step), so the agent knows exactly what surface this tool covers. It does not explicitly name or distinguish itself from siblings like edit_step or edit_milestone, which is the only thing keeping it from 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 through conditional semantics ('For a weekly routine, count says...', 'For a routine, level minimum...'), which tells the agent when certain parameters apply. However, there is no explicit guidance on when to use edit_plan_item versus set_plan, edit_step, or edit_milestone, leaving alternative routing 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 a non-destructive, idempotent mutation, so the bar is lower. The description adds real behavioral context beyond them: the session 'is classified again after a change' (a side effect on derived classification) and the end-before-start rule implying an overnight span. It does not mention permissions or how partial updates behave.

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 verb and resource, then the field list, then the usage note. The long field enumeration is dense but earns its place across 15 parameters, and there is no filler.

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

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

For a 15-parameter mutation with no output schema, the description covers what can be changed, when to reach for it, and the reclassification side effect. A reader still has to consult the schema for enum values, defaults and id/format details, which is acceptable but leaves minor gaps.

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

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

Schema coverage is 60%, so the description carries part of the burden. It groups the mutable fields into one readable list and adds genuine semantics the schema lacks: the midnight-crossing rule for a start/end whose end precedes the start. Otherwise the field enumeration largely mirrors schema property names.

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 (fix/edit) and resource (session) and enumerates exactly what is editable: start, end, task, area, project, lever, step, plan item, summary, outcome, attention share, weight. It also scopes the target as 'running or finished', which cleanly separates it from add_session, delete_session, start_session and stop_session.

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

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

Gives explicit triggering conditions: 'Use it when a timer was forgotten or a session was labelled wrong.' That is a clear when-to-use signal. It stops short of naming alternatives (e.g. split_attention for dividing attention, stop_timer for live timers) or stating when-not to use it, so no full routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the scope is a single step, but it does not disclose partial-vs-full update semantics (whether omitted fields are preserved), permission requirements, or what happens to the other steps' ordering when 'order' changes.

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, front-loaded with the verb and scope, followed by the field list. No filler, no redundancy.

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

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

For a 6-parameter mutation tool with no output schema, the description covers the field names but leaves out the required stepId, partial-update behavior, and any return/confirmation information. It is minimally 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?

With 0% schema description coverage, the description must carry the parameter burden, and it does name most editable fields (title, status, order, lever, estimate). However, it omits the required stepId identifier, does not clarify units for estimateMin (minutes?), does not explain 'lever' vs the schema's leverId, or the meaning/range of 'order', so the compensation is only partial.

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 gives a specific verb (Change) plus resource (one step) and enumerates the mutable fields, so it is clearly distinguishable from edit_milestone, edit_plan_item, and edit_session by resource. It stops short of naming those siblings or the delete_step alternative explicitly, so it is clear but not maximally differentiating.

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 statement of when to use this tool versus delete_step, add_steps, or the other edit_* tools, and no prerequisites (e.g., the step must already exist). The only implied guidance is that this modifies an existing step, which the agent must infer.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds the concrete detection threshold (20+ minutes) and the anchoring boundaries (between first and last session of the day), which is genuinely useful behavioral context, but it says nothing about the shape of the returned data.

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 definition of a gap. Tight and waste-free, though the second sentence is a behavioral instruction rather than descriptive content.

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 query with full schema coverage and no output schema, the definition supplies the key semantics (what counts as a gap). It could go slightly further on what the call returns, but the essentials an agent needs are present.

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

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

Schema coverage is 100% and the 'date' parameter is fully documented in the schema ('YYYY-MM-DD in the user's timezone'). The description's 'of a day' only loosely corroborates that the date scopes to a single day, adding little beyond the schema baseline of 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?

Names a specific resource ('gaps') and defines it precisely as 'untimed stretches of 20+ minutes between the first and last session of a day'. No sibling tool competes with this concept, so the agent can identify it readily, though it is phrased as a noun fragment rather than a verb+resource statement.

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 trailing 'Ask the user what happened there' implies a follow-up workflow, giving some sense of intended use. However, it never says when to call this tool versus alternatives (e.g. summarize_day), nor any prerequisite or exclusion; 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 establish this is a safe, read-only, idempotent operation, so the safety profile is covered. The description adds the useful defaults and the taxonomy of leak types it surfaces, but says nothing about the output shape or how the analysis is computed beyond the category list.

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?

It is a single front-loaded sentence plus a short default-range clause with no filler. The enumeration of categories is dense but every item earns its place as a definition of what a 'leak' is.

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 analysis tool with no required params and annotations covering safety, the description is largely sufficient — it defines the leak taxonomy (effectively the return content) and the default range. It lacks sibling-based routing guidance (find_gaps vs find_leaks), which is the main remaining gap.

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

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

Schema coverage is 100%, so the format of from/to is documented. The description adds the default window ('Default the last 7 days'), which the schema does not convey, giving it slightly more value than the baseline 3.

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

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

The description states a recognizable purpose — identifying where time leaks — and enumerates the specific leak categories (goal work while the main step waited, overrides, unplanned work, switching, missed main steps, etc.), which is specific and distinctive. It does not, however, differentiate itself from the sibling tool find_gaps, which seems closely related given 'gaps' is listed as one leak category.

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 guidance offered is 'Default the last 7 days,' which addresses the time window but says nothing about when to choose this tool over alternatives like find_gaps or summarize_day. There are no when-to-use or when-not 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety and determinism profile is fully covered by structured data. The description adds only that the result is a computed budget breakdown with explicit 'unaccounted for' accounting, plus the ambiguous 'Nothing is assumed' remark, which is too vague to count as real behavioral disclosure.

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

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

Two tight sentences, front-loaded with the core concept (168-hour weekly budget) followed by the breakdown components. No wasted text, though the trailing 'Nothing is assumed' is an unclear fragment that slightly dilutes it.

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 carries the burden of describing the return value, and it does enumerate the main components (overhead, committed hours per area, focus windows, unaccounted time). It is adequate for a parameterless read tool, with only the vague final sentence leaving residual ambiguity.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline for a parameterless tool is 4. The description correctly implies no input 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 states a specific resource — a weekly 168-hour time budget — and enumerates what it contains (overhead, hours committed per area, focus windows, unaccounted time), which is more informative than the title alone. It does not, however, distinguish itself from close siblings like summarize_week, find_gaps, or get_planning_context, which an agent would need in order to choose correctly.

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 statement of when to call this versus alternatives such as summarize_week or find_gaps, and no prerequisites or context triggers are given. The closing phrase 'Nothing is assumed' is cryptic and does not function as usable 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 carry readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the nature of the returned data (recurring weekly time blocks), but says nothing about scope, filtering, or freshness since there is no output schema to lean on.

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 covering the resource and its contents with no filler. It is efficient, though the elliptical noun-phrase style means no explicit verb is stated.

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 no annotations covering the data shape, the description must explain returns; it names the three categories but not their structure, ordering, or time horizon beyond 'weekly'. Adequate for a simple parameterless read, but thin for a tool whose output the agent must interpret.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description correctly implies a parameterless full retrieval and introduces no misleading argument expectations.

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 precisely and enumerates the three categories it returns (commitments, overhead, focus windows) with concrete examples, so an agent knows what data comes back. It doesn't explicitly contrast with the sibling set_commitments, so it falls short of a 5.

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

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

There is no guidance on when to call this versus alternatives such as get_routines, get_capacity, get_planning_context, or the writing counterpart set_commitments. The agent must infer usage entirely from the tool name.

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

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

Annotations already establish readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine value beyond that by disclosing what the payload contains, which matters because there is no output schema. It stops short of describing progress/lever semantics or a return shape for empty state.

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

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

The description is a single dense sentence that front-loads the resource and then lists the returned fields, with the ordering advice appended. Every element earns its place, though the comma run-on list is slightly harder to scan than a structured breakdown would be.

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

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

With no output schema, the description carries the burden of telling the agent what it receives, and it does so by enumerating nine returned fields. It is nearly complete for a trivial zero-param reader, missing only interpretation of items like lever categories (hard/comfortable) and how progress is expressed.

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

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

The tool takes zero parameters, so the schema itself fully covers the input surface and the description has no parameter burden to carry. The baseline for a 0-param tool is 4, and nothing in the text conflicts with the empty schema.

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

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

The description names a specific resource (the singular yearly goal) and enumerates the exact fields it surfaces (kind, metric, starting value, current value, target, deadline, progress, levers, other projects), so an agent knows precisely what comes back. It falls short of 5 only because it does not explicitly contrast itself with the sibling set_goal or check_goal_draft, though 'the one yearly goal' implies uniqueness well enough to distinguish it.

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 single instruction 'Call first in most flows' gives ordering guidance, which is useful context about when to invoke it. However, 'most flows' is vague and no exclusions or named alternatives (e.g. get_planning_context or get_plan) are offered, so usage is implied rather than fully specified.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety bar is met without the description. On top of that the description adds real behavioral context: the window is rolling and anchored to `to`, the heatmap is bounded to 6:00–23:00 Mon–Sun, and comebacks use a 90-day lookback and wall-clock minutes of finished sessions as displayed in the app — non-obvious computation details absent from annotations. It stops short of stating timezone handling or response shape, 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?

It is front-loaded with the window definition and contains no filler, but the second half is one long comma-spliced run-on listing five distinct metrics, which makes it hard to scan. A short bulleted metric list would communicate the same content with less parsing cost.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating every metric included in the report, which is strong. It leaves out units/timing edge cases (e.g., timezone used to compute daily boundaries, what an empty range returns), which matters for a time-bucketed analytics 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 100%, establishing a baseline of 3. The description still earns credit by adding semantics the schema lacks: it defines week as the last 7 days and month as the last 30 days ending on `to`, clarifying that these are rolling windows rather than calendar periods.

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

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

The description clearly establishes that this is a period-reporting tool and enumerates the exact metrics returned (minutes per day, hard/comfortable share, heatmap, main-step days, comebacks), so an agent knows what it gets. It never contrasts itself with the obvious siblings summarize_day and summarize_week, even though the outputs overlap heavily, leaving the agent to guess which reporting tool to pick.

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 via the range/defaults semantics ('default today', 'default week'); there is no explicit statement of when to call this instead of summarize_week, summarize_day, or get_capacity. The comebacks lookback ('over 90 days') is the only scoping hint, and it is presented as a metric description rather than routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so safety is covered. The description's real contribution is disclosing the shape of the payload (sessions with attention shares, timer, main step, minutes, streak, nudge), which matters because no output schema exists.

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

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

A single sentence with no preamble and no waste; the most important element (what is happening now) is front-loaded before the colon, and the return fields follow compactly.

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 is the sole source of return-value information, and it enumerates the payload fields adequately for a zero-argument read tool. It stops short of anything about freshness, ordering or how empty states appear.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The schema is empty and fully described, and there is no parameter syntax the description could usefully add.

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

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

The description concretely enumerates what the tool returns: running sessions with attention shares, the timer, today's main step, minutes, streak and a nudge. That content list makes it clearly distinct from summarize_day, get_plan or get_capacity, even though no sibling is named. The verb itself is only implied by the title 'Get now', which keeps it from 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?

There is no statement of when to call this versus alternatives such as summarize_day, get_planning_context or get_path, and no prerequisites or exclusions. The dashboard-like content implies a 'current status' use case, but the agent has to infer it entirely.

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

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

Annotations already establish readOnly, idempotent, closed-world safety, so the description correctly spends its budget on data semantics instead: how current_milestone_id is derived per track (first open one in list order) and that every track has its own current milestone. That is genuinely useful context an agent could not get from the annotations. It stops short of describing ordering or what 'kind' and 'pace' enumerate.

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?

Dense and jargon-heavy, and it is not front-loaded: the first sentence dives into field-level detail before establishing what the tool returns as a whole. Nothing is obviously redundant, but a one-line purpose statement ahead of the field notes would earn its place.

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

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

With no output schema, the description carries the full burden of explaining return shape, and it covers the track/current-milestone logic well. However, it never states the top-level structure (single object vs. list), milestone ordering, or the allowed values of 'kind' and 'pace', leaving gaps for a zero-input tool whose entire value is its output.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description's space is well used on return semantics rather than phantom inputs.

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 text reads as a return-value spec ('Milestones with kind, progress, pace and their steps') rather than a statement of what the tool does; there is no verb such as 'retrieve' and 'path' is never defined. An agent can infer it fetches milestones/tracks, but it cannot distinguish this from get_plan, get_goal, or next_steps from the description alone.

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 call this versus sibling readers like get_plan, get_planning_context, or next_steps. The 'With tracks… / Without tracks…' clauses describe how to interpret output, not when to choose this tool, so selection is left entirely to inference from the name.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered externally. The description adds nothing beyond that – no note on what the returned plan contains, whether it mixes sessions/tasks/milestones, or how empty days behave.

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?

It is a single fragment with zero waste and the default is front-loaded, which is efficient. However, terse under-specification is not the same as good conciseness; the sentence omits the verb and any structure, leaning on the title to carry meaning.

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 retrieval tool with no output schema, the description should convey at least roughly what a 'plan' object is (items, sessions, goals) and whether an absent day returns empty or an error. None of that is present, leaving the agent able to call it but not to know what it will get back.

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

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

Schema description coverage is 100% for the single date parameter, which already documents the YYYY-MM-DD format and user-timezone semantics. The description's '(default today)' adds the default behavior that the schema omits, but that is a marginal increment, so the baseline 3 applies.

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

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

The description is a noun phrase, 'The plan for a day (default today)', with no verb, but it does identify the resource (the day's plan) and a scope. It does nothing to distinguish itself from close siblings like get_planning_context, next_steps, get_commitments, or get_routines, so an agent must guess which retrieval tool it wants.

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 '(default today)' hints that the date can be omitted, which is mild usage guidance. There is no statement of when to prefer this over the other plan/context/goal readers in the sibling list, and no exclusions or 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 readOnly, idempotent, non-destructive, so safety is covered. The description adds useful behavior: it defaults to tomorrow and describes the aggregated content returned, which the annotations do not convey. No output schema exists, so this enumeration carries real weight.

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 compact sentences, front-loaded with the payload contents, then the default, then the workflow routing. Every sentence earns its place with no redundancy.

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

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

For a single-optional-param, read-only tool, the description lists the returned context and the default date, compensating for the absent output schema. Coverage is nearly complete, though it doesn't state the response format or the date-selection effect on the aggregate windows.

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 format (YYYY-MM-DD, user timezone) is already documented. The description adds the default behavior ('Defaults to tomorrow'), which is meaningful semantics not present in the schema, exceeding the baseline 3.

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

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

States a specific resource (a bundle of planning context) and enumerates its contents: goal and pace, next_steps, yesterday's summary and undone items, week balance, days since a hard lever. It also distinguishes its role from siblings by noting the agent plans and then calls set_plan rather than get_plan/next_steps.

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?

Clearly positions this as the first step of a planning workflow and names the follow-up tool (set_plan), which is strong context. It lacks explicit 'when not to use' exclusions (e.g., versus get_plan or next_steps), so it stops short of the top score.

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

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

With annotations already covering read-only, idempotent, open-world, and non-destructive behavior, the description adds substantial context: the draft is capped at 300 characters, ends with 'aimyear.com', and includes per-network statuses (ready, already posted, or skipped because the user posted there). It reinforces 'Posts nothing,' which clarifies the potentially misleading name. Auth and rate-limit details are absent, so a 4 is appropriate.

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

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

The description is a single dense sentence with a semicolon, front-loading the primary purpose. Every clause adds useful information (content fields, character limit, domain suffix, network states), though the parenthetical enumeration is somewhat long. It is efficient but could be broken into clearer clauses.

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?

No output schema exists, so the description must carry return-value information. It does by detailing the draft's content, max 300 characters, domain suffix, and per-network posting statuses. Combined with annotations covering safety and schema covering the date parameter, this is nearly complete for a read-only tool; only the exact return structure (field names/shape) is unspecified.

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% for the single date parameter, so the schema already documents format and timezone. The description only implies date via 'The day's' and does not add syntax or format details beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description clearly states it drafts the day's progress post from the record, enumerating the content (aim and progress, main step done, minutes on aim/hard work, routines, comebacks) and per-network statuses. It distinguishes from add_post by stating 'Posts nothing.' However, it doesn't explicitly name the alternative tool for posting, so it falls just short of perfect 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: use this to preview a draft rather than post, reinforced by 'Posts nothing.' But there is no explicit when-to-use guidance or direct reference to siblings (e.g., 'use add_post to publish'). The agent must infer the context from the description.

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 readOnly, idempotent, non-destructive, and closed-world behavior, but the description adds useful context: server-side plan insertion, shared visibility across devices and agents, and fallback starters when no routines exist. Return shape is still unspecified, but this goes meaningfully beyond the annotations.

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

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

The three sentences are not obviously padded, but the first sentence defines the domain rather than front-loading the tool's action. It is reasonably sized yet could lead more directly with what the tool returns.

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

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

For a zero-parameter read-only tool with rich annotations and no output schema, the description supplies useful domain context and empty-state behavior. However, it does not clarify the general return structure or explicitly confirm the retrieval action, leaving minor gaps.

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

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

There are no parameters, so the baseline for zero-parameter tools is 4. The description does not need to compensate for any schema gaps.

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

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

The description explains what routines are and mentions a fallback return of starter routines, but it never states the core action ('returns the current routines') and does not differentiate this getter from set_routines. The reader can infer retrieval from the name and title, but the text itself is domain exposition rather than a tool purpose.

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 when-to-use guidance, prerequisites, or alternatives are given. It does not mention set_routines or explain when an agent should call this tool instead of any sibling.

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, idempotentHint=true and destructiveHint=false, so safety behavior needs no repeating. The field enumeration adds useful context about what the call exposes (reminder destination, tracking mode, post_to networks), which partially substitutes for the missing output schema, but nothing is said about permissions, defaults, or whether values can be null/unset.

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 that leads with the highest-value items and contains no filler. It loses a point because it is a bare fragment with no anchor verb and the parenthetical lists ('desktop or mobile', 'time, moves or quiet') make it read like raw schema text rather than guidance.

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

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

For a zero-parameter read tool with no output schema, the description does the main work of telling the agent what comes back, covering the major settings groups an agent would need. It stops short of stating the return shape (flat object vs nested) or noting that fields may be absent if unset.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing the description could add about inputs. The enumerated keys do at least align vocabulary with what set_settings would accept, which is mild extra value.

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 is a noun-phrase enumeration of the settings fields ('Timezone', 'reminders', 'timer settings', 'post_to', 'tracking', 'weekly target') without ever stating a verb such as 'returns' or 'reads'. Combined with the name and title the intent is inferable, but nothing distinguishes it explicitly from set_settings or get_capacity; the reader must supply the retrieval framing themselves.

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 statement of when to call this versus alternatives, no mention that set_settings is the write counterpart, and no prerequisite or exclusion guidance. The only implicit cue is the field list, which hints at configuration data rather than plan or progress data.

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, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description only needs to add context beyond that. It usefully discloses what is returned (name, client_id, connection time, last-active time) and that 'current marks the one calling', which helps the agent interpret the result. It stops short of stating ordering or whether the list is exhaustive, but the added context is meaningful.

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. Every clause earns its place: scope, examples, returned fields, and the special 'current' flag.

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 carries the burden of explaining return values; it does so by listing the key fields and the 'current' marker. For a no-argument read tool this is nearly complete, with only minor gaps around ordering and whether pagination applies.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric. No parameter semantics are needed, and the description correctly does not invent any.

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 ('Agents connected to this AimYear account') and enumerates the concrete clients (Claude, ChatGPT, Claude Code, the AimYear app). It also names the returned fields, so an agent can distinguish this from siblings like list_devices or list_social_accounts 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?

Usage is only implied: the tool lists connected agents, so an agent can infer when to call it. There is no explicit when-to-use/when-not guidance and no mention of alternatives such as list_devices, 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is fully covered. The description adds only the semantic content of the result set (which devices, last-seen time), with nothing about ordering or result size. Marginal added value over structured fields.

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

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

A single short sentence with no padding, and the key content is front-loaded. It reads as a noun phrase rather than a complete definition sentence, which is a minor structural weakness but costs nothing in length.

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

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

For a zero-parameter, read-only, non-destructive listing with full annotation coverage and no output schema, the description conveys what the agent will receive. The missing piece is usage context relative to its siblings, but nothing required to invoke it correctly is absent.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain and the baseline is 4. Schema coverage is 100% on an empty object, leaving nothing for the description to compensate 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?

The sentence describes the tool's output scope (devices eligible for reminders, plus last-seen timestamps) but never states a verb, so the purpose is only implied by the name and title. It also does no work to distinguish this from add_device or delete_device beyond the obvious read/write split.

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, no prerequisites, and no mention of the sibling tools (add_device, delete_device, list_sessions) that an agent would need to choose correctly. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real context beyond that — the default 7-day window and the per-move fields returned (ids, toward-aim, hard-part flag) — but says nothing about ordering, result limits, or behavior when only one bound is supplied.

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

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

A single sentence that front-loads the resource, then the range and its default, then the returned fields. No filler, no restatement of the title.

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

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

For a simple two-optional-param read tool with no output schema and full annotation coverage, the definition covers purpose, default range, and return content adequately. It stops short of describing ordering or volume of results, which an agent may need to decide between this and the summary/gap 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% and both params document the YYYY-MM-DD format in the user's timezone. The description still adds meaning the schema lacks: that the range is optional and defaults to the last 7 days when omitted, which materially affects how an agent calls it.

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 (list) and resource (moves) and scopes it to a date range, so the agent knows exactly what comes back. It does not name a sibling alternative, but the resource is distinct from list_sessions/list_devices/list_agents, so separation is largely self-evident.

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: this is the read path for moves, with a stated default window of the last 7 days. There is no explicit guidance on when to prefer it over adjacent analytics tools like summarize_day, find_gaps, next_steps, or get_path, and no stated exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds genuinely new context beyond them: the default range is the last 7 days and results carry ids, which an agent needs to reason about output and defaults.

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 with the subject and default window front-loaded and qualifiers following. It wastes no words, though it could be marginally clearer about the optional filtering.

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 list tool with full annotations but no output schema, the definition is adequate but thin: it does not mention pagination, result caps, sort order, or the shape of returned session objects beyond "ids". The essentials for calling it are present, but not the full behavioral picture.

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 50% schema coverage, from/to carry their format in the schema and area exposes its enum there, so the description's contribution is mainly mapping "project" to projectId. The projectId parameter itself remains undocumented in both the schema and the description, leaving the coverage gap only partially compensated.

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 (sessions), the scoping (a date range with a 7-day default), and the returned identifier fields. It is clearly distinguishable from the mutation siblings add_session, edit_session, and delete_session, though it never states an explicit verb like "list".

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 conveys the default window and the optional area/project filters, which implies a browsing use case. However, it offers no explicit when-to-use guidance versus alternatives such as summarize_day/summarize_week or find_gaps, and no exclusions or 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds real value beyond that: it discloses the returned fields (handle, connection date, progress-post eligibility, Pro status) and a security guarantee that no keys or passwords are exposed.

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 densely-packed sentence with no waste, and the payload contents are front-loaded. The parenthetical phrasing is slightly compressed but not unclear.

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 no annotations about return shape, the description carries the burden of explaining what comes back, and it does so concretely. It stops short of noting ordering or volume, which for an unfiltered per-user list 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?

The tool takes zero parameters, so there is nothing to disambiguate; baseline is 4. The description correctly describes an unfiltered listing with no mention of arguments.

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 (connected social networks) and enumerates the fields returned, so an agent knows exactly what this tool yields. It is implicitly distinguishable from add_social_account/delete_social_account by the list-vs-mutate verb, but never names those siblings 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?

Usage is implied by the verb 'list' and by the sibling set containing add/delete_social_account, so an agent can infer when to call it. However, there is no explicit when-to-use statement or routing to an alternative.

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 (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral detail beyond them: the result set spans every track 'taken in turns', each step is annotated with its track, and ordering puts hard-lever steps first. It stops short of describing pagination/return shape or how ties are broken, but that is a minor gap given 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?

A single sentence, front-loaded with the resource and scope, with no filler. The nested parenthetical makes it slightly harder to parse than necessary, 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?

For a read-only list tool with no output schema and one optional param, the description conveys the conceptual shape of the result (steps grouped by track, ordered by lever priority). It still omits the 'count' behavior, the default size, and what a 'hard-lever' step is, which an agent needs to use 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?

The schema has one optional parameter, 'count' (1-20), with 0% description coverage, and the description never mentions it — no default, no meaning, no note that it caps the returned list. With low schema coverage the description was expected to compensate, and it does not.

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 ('open steps of the current milestone') and its ordering ('hard-lever steps first'), so the general purpose is discernible. But there is no explicit verb ('returns'/'lists') and heavy domain jargon ('tracks', 'hard-lever steps') is never unpacked, leaving the agent to infer what the output actually is. It does not distinguish itself from close siblings like get_plan, get_path, or get_planning_context.

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 trailing clause 'the candidates for today's main step' implies the use case — picking today's focus — but there is no explicit when-to-use, when-not, or named alternative among the many planning siblings. Usage must be inferred from the phrase rather than stated.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description reinforces this with 'calling again for the same date corrects it' plus the side effect that a milestone reaching its target becomes done. That side-effect disclosure is genuine added value beyond the annotation set.

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 the core action, then examples, then the per-date correction rule and target-reached behavior. Dense but every clause carries information; nothing is 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?

For a small mutation tool with no output schema, the description covers what the value means, the per-date overwrite rule, and the milestone completion side effect. Return format is only hinted at ('Says when the target is reached'), which is a minor residual gap.

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

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

Schema coverage is 67% (value has no schema description), but the description compensates by defining value semantics ('1 marks it done' for done-or-not goals) and clarifying that milestoneId targets a countable milestone rather than the goal. This adds meaning the schema alone does not convey.

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

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

States a specific verb (record) and resource (the goal metric value, or a countable milestone when milestoneId is given), with concrete examples that make the intent unmistakable. It is clearly distinguishable from sibling setters like set_goal or edit_milestone.

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?

Explains when to pass milestoneId versus recording the goal metric, gives example phrasings, and clarifies the 'one value per date, call again to correct' convention. It stops short of naming an alternative tool or stating exclusions, but the usage 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: 'Replace' clarifies that the whole list is swapped, and 'Pass existing ids to keep them' tells the agent how to avoid losing existing entries during a destructive replace.

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. The replace semantics lead, followed by the two rules an agent needs. 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 complex nested-array parameter with no output schema, the description covers the destructive-replace behavior, id preservation, and the ambiguous days encoding. It stops short of explaining how the nested kinds (commitment/overhead/window) interact, but the schema carries those.

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 gives no top-level description for the commitments array and no description for days, so the description must compensate. It does: 'days are ISO weekdays 1=Mon..7=Sun' supplies the encoding that the schema omits, and it explains the days-vs-timesPerWeek tradeoff. It does not cover the many nested fields, but those are documented inside the schema.

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

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

States a specific verb and resource: 'Replace the list of recurring weekly commitments.' An agent knows exactly what is being mutated. However, it never distinguishes itself from the closely related sibling set_routines, which an agent could easily confuse with weekly commitments.

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 in-parameter rule of thumb ('use timesPerWeek instead when there are no fixed days') and a preservation rule ('Pass existing ids to keep them'), which is useful. But there is no guidance on when to call this versus set_routines or get_commitments, so usage context is only partially covered.

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

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

Annotations only declare write/idempotent/non-destructive. The description adds real behavioral context beyond them: 'off' means timer and reminders only, nothing stored, no plan required, and 'full' is the default. It does not clarify what happens to already-recorded data when switching to 'off', which is the one consequential ambiguity.

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 dense sentence with no filler, and the two modes are presented in a clean parallel structure with the default flagged immediately. The compression makes it slightly terse to parse 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?

For a two-parameter toggle with no output schema, the description covers mode semantics and the safety story is carried by annotations. It still omits the date-default behavior and whether prior recorded data is affected by switching to 'off' — a meaningful gap 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 coverage is 50% and the mode enum carries no inline description, so the description does the work by defining both values ('full' = everything recorded, default; 'off' = timer and reminders only). It compensates well for the enum but says nothing about omitting 'date', leaving that parameter's absence behavior 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?

The description states the resource ('Tracking for a day') and enumerates the two possible states, so an agent can tell this is the switch controlling whether a day's data is recorded, distinct from set_settings or set_routines. It is slightly noun-phrase-led rather than verb-led ('Set...'), but the intent 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?

It gives useful selection context by naming 'full' as the default and explaining what 'off' means, which implicitly tells the agent which value to pick. However, it never states when to call this tool versus siblings like set_settings, nor any prerequisites or exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful context beyond that: a failed rubric returns problems[], and replacing a goal preserves levers and projects. It does not fully spell out what is overwritten, but the added behavioral detail is meaningful.

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

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

Four short sentences, with the core save/replace action front-loaded. Every sentence contributes something, though the area sentence is somewhat redundant with the schema enum.

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

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

For a destructive, eight-parameter mutation with no output schema, the description covers purpose, failure behavior, and preservation of levers/projects. It still leaves important context gap, especially the relationship to check_goal_draft and the exact replacement/destruction semantics.

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%, so most parameter meaning is already documented. The description only clarifies that area is one of five life areas, which adds little beyond the enum and default already present in 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?

The description states a specific verb and resource: save or replace the yearly goal. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like get_goal or check_goal_draft.

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: use this to save or replace the yearly goal. The description does not state when to prefer check_goal_draft, when not to replace an existing goal, or any prerequisites, so guidance is only inferable.

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, and the description adds real value beyond them: it clarifies full-replacement semantics, a hard validation rule ('At least one must be kind=hard'), and the id-preservation trick ('Pass existing ids to keep them'), which is exactly the behavior an agent needs to avoid clobbering data. It still does not say what happens to sessions classified under removed levers.

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 compact sentences, front-loaded with the replace action, then the validation constraint, then field hints. Dense but each sentence carries information; 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?

For a destructive, single-parameter replace tool with no output schema, the description covers semantics, validation, and the id-preservation pattern needed to avoid unintended destruction. Minor gaps remain (fate of sessions tied to removed levers, required 'name'), keeping it short of a 5.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does: it explains id (pass to keep), kind (must include hard), and that keywords/repos are classification hints from session task text. It omits 'name' and 'examples', but those are self-evident from the schema.

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

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

States a specific verb and resource ('Replace the list of levers') and even defines the domain term ('the recurring kinds of goal work'), which is not obvious from the name alone. It aligns with the set_* sibling family but does not name any sibling to differentiate itself 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?

There is no when-to-use or when-not-to-use guidance, and no mention of alternatives like set_commitments, set_plan, or set_routines that also replace list-like state. The replacement semantics are implied by 'Replace the list' but an agent gets no routing help.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description supplies the consequence that matters: omitting an existing id deletes that milestone's steps. That is the key non-obvious destructive detail an agent cannot infer from the annotations alone.

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

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

Everything present earns its place and the replacement semantics are front-loaded, but it is a single dense run-on sentence built from semicolons and parentheticals, which is harder to parse than it needs to be for a constraint-heavy tool.

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

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

For a single-array-parameter, destructive replace operation with no output schema, the description covers limits, ordering, id semantics, and the alternative tool. The remaining minor gap is not stating explicitly that milestones omitted from the array are removed, beyond the implied consequences of 'Replace' and the id rule.

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 description adds real meaning beyond the schema: the 2–6 count limit, the six-per-track cap, the due-before-goal-deadline and within-track ordering rules, and the 'pass each existing id' contract that governs create-vs-update vs delete. It leaves metric/target values largely to the schema's own nested descriptions, so it is strong but not exhaustive.

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

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

Opens with a specific verb and resource ('Replace the list of ordered milestones under the goal') and scopes the operation as a full replacement rather than a per-item edit. It explicitly names the sibling edit_milestone as the tool for single-milestone changes, so an agent can route without opening either schema.

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

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

States the selection condition against an alternative directly: 'To change one milestone, use edit_milestone.' It also encodes the applicable constraints (2–6, or up to 6 per track, due before the goal deadline, due dates ordered within a track), so the agent knows both when this tool applies and what input will be rejected.

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 adds behavior the annotations do not: it emits a warning when no item is on a hard lever, and items that remain 'keep their done state.' That is genuine behavioral disclosure beyond structured fields.

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

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

Front-loaded with the core action ('Replace the plan for a day') followed by the key invariant and edge-case notes. Four short sentences, no filler. The 'Other items: paid work, family, workout, etc. with their area' clause is slightly telegraphic but earns its place by mapping examples to the area field.

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

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

For a destructive, idempotent mutation with no output schema, the description covers the critical domain invariant (single main step), warning behavior, and done-state retention, with safety carried by annotations. Gaps remain around how date defaults and the unused optional fields, but nothing essential to a correct call is missing.

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

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

Schema coverage is 50%, and the description compensates by explaining isMainStep (exactly one must be true), the provenance of stepId (from next_steps), the hard-lever linkage for leverId, and the intent of area (paid work, family, workout, etc.). It leaves projectId, estimateMin, and the date format undocumented, so it is helpful but not exhaustive.

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 with scope: 'Replace the plan for a day.' This implicitly separates it from item-level siblings like edit_plan_item and delete_plan_item (whole-plan replacement vs single-item edit). It does not name any sibling explicitly, so it falls short of full differentiation.

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

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

It gives content rules for a valid call (exactly one isMainStep=true, ideally linked via stepId from next_steps, on a hard lever) rather than guidance on when to call this versus edit_plan_item, delete_plan_item, or add_steps. Usage is implied by 'Replace the plan for a day' but no when-not conditions or alternatives are stated.

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

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

Annotations flag destructiveHint=true and idempotentHint=true, and the description goes beyond them by spelling out exactly what destruction means: omitted projects are removed. It also implies idempotence (pass the whole list). It doesn't note side effects on existing sessions or auth requirements, but the destructive mechanics are well disclosed.

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 tightly packed sentences, purpose front-loaded, and each clause adds usable information (scope, replace semantics, id retention). 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?

For a destructive, no-output-schema mutation tool with annotations already covering safety, the description supplies the essential replace/keep/remove semantics. Minor gaps remain around the unmentioned area and repos fields and downstream effects on existing sessions.

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 0% for a single, nested array-of-objects parameter. The description clarifies the id field ("pass existing ids to keep them") and name/hints for editing, but the area enum and repos field are documented nowhere. It partially compensates but leaves meaningful gaps.

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

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

States a specific verb ("Replace") and resource ("the list of other projects"), and defines that resource concretely (paid work, other products, life routines) with its effect (sessions count as other work or life, not goal work). It implicitly distinguishes this from goal work, though it does not name a specific sibling tool.

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

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

The description gives clear operating instructions for the replace semantics: leave an item out to remove it, change name/hints to edit, pass existing ids to keep. That tells the agent how to invoke it correctly. It stops short of stating when to prefer this over alternatives like set_goal or set_levers.

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

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

Annotations already mark the tool as destructive and idempotent; the description adds important behavioral detail about replacement, preserving existing ids, plan-item appearance, and perWeek reset behavior. It makes the destructive semantics concrete: omitted routines are effectively removed unless existing ids are passed.

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

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

The description is front-loaded with the core purpose and nearly every clause carries useful meaning. It is dense and could be structured more clearly, but it is not padded or repetitive.

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

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

For a destructive, nested-array mutation tool with no output schema, the description covers the important lifecycle and parameter behavior. Minor gaps around some nested fields prevent a perfect score.

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

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

Although schema description coverage is reported as 0%, the description explains key semantics for days, perWeek, leverId, minimum, and id retention. It leaves area, projectId, and estimateMin less explained, so it compensates substantially but not completely.

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: "Replace the list of routines," then defines routines as recurring weekday steps. It also distinguishes behavior from related tools by naming edit_plan_item, delete_plan_item, and set_plan.

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?

Explains how routines are acted on after creation and that set_plan keeps them, which gives clear operational context. It does not explicitly state when not to use this tool versus set_plan, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so safety is largely covered. The description adds real behavioral context for specific fields (timezone determines where each day starts and ends; tracking=quiet means reviews and posts speak in words and days, never minutes or percentages). It does not state whether omitted settings are preserved or reset, nor whether changes take effect immediately or on the next day boundary.

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 the imperative verb first and every clause mapping to a real parameter, so nothing is filler. It is dense and slightly run-on, making the field list harder to scan than a short bulleted grouping would be, but it wastes no 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 10-parameter mutation tool with 30% schema coverage and no output schema, the description covers the what of each field but not the return value or whether unspecified settings are left untouched. It is adequate to invoke the tool on a known field, but an agent still has to open the schema to learn ranges and would not know what the call reports back.

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

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

With only 30% schema description coverage across 10 parameters, the description carries most of the explanatory load and largely delivers: it gives the IANA format and day-boundary meaning for timezone, ties workplace to reminders, names the stand-up interval group (workMin, breakMin, longBreakEvery, longBreakMin), explains post_to as the networks receiving progress posts, and describes tracking modes. Gaps remain for longBreakEvery (units/interval semantics) and the units/ranges of the workMin/breakMin/longBreakMin fields, which are only inferable from the names.

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 ("Change") and names the resource implicitly as the settings object, then enumerates the exact fields it can modify, so an agent can distinguish it from the read counterpart get_settings and from the many set_* siblings. It stops short of naming get_settings as the read alternative, which keeps it out of 5 territory.

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?

"Change any of:" implies partial-update semantics (you may pass a subset), which is useful but only implied, not stated. There is no explicit guidance on when to use this versus set_routines, set_levers, set_commitments, or get_settings, and no mention of prerequisites or ordering.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds useful behavior beyond that: the 0-3 track limit, the replace semantics, and the empty-list reset behavior. It does not mention permissions or side effects on existing milestones beyond replacement.

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

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

The core action is front-loaded with 'Replace the tracks of the path'. The remaining sentences explain the model, field meanings, and usage guidance without excessive padding, though the phrasing is a bit dense and could be slightly tighter.

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 mutation tool with no output schema and full annotation coverage, the description supplies the essential structure: 0-3 tracks, per-track reach and milestoneIds ordering, and reset behavior via an empty list. It is complete enough to invoke correctly, missing only minor details like how existing tracks are removed.

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 parameter meaning. It explains that 'reach' says how a track alone would reach the aim, and that 'milestoneIds' puts milestones into the track in that order. It also clarifies the empty-list behavior, though it does not explicitly define 'id' or 'title'.

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

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

The description opens with a specific verb and resource: 'Replace the tracks of the path', then defines tracks as 0 to 3 alternative ways to reach the same aim. This clearly distinguishes the operation from sibling tools like set_milestones or set_plan by scoping it to multi-path 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?

It gives a clear usage condition: 'Use tracks only when the user chooses to work on more than one way' and warns 'never present one track as the wrong one.' It also explains that an empty list collapses the path back to a single list. However, it does not name a specific alternative tool for the single-path case.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is carried by structured data. The description adds the scope of effect ('at once', 'Applies to the whole session'), which is real value, but it says nothing about permissions, conflicts, or how omitted sessions are handled.

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 plus an inline example; the core action is front-loaded and every element (set weights, whole-session scope, finished-session alternative) earns its place with no filler.

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

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

For a batch mutation with a nested-object parameter and 0% schema coverage, the description covers purpose, scope, and the sibling alternative, and annotations cover the safety profile (no output schema needed). The remaining gap is parameter meaning—keys, summation, and partial-update semantics—which leaves it adequate but under-specified.

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

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

Schema description coverage is 0% on a required nested object, so the description bears compensating weight. The inline example {"abc": 0.7, "def": 0.3} does show the key→number shape, but the description never states that keys are session identifiers, whether weights must sum to 1, or how excluded sessions behave.

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 gives a specific verb and resource ('Set attention weights of the running sessions') plus a concrete data example, and it explicitly names a sibling case ('For a finished session use edit_session'). The concept 'attention weights' is domain jargon left unexplained, and it does not distinguish itself from other set_* tools, so it falls just short of a 5.

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

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

It states the operative condition ('running sessions') and gives an explicit alternative for the finished-session case ('use edit_session'). It does not cover the broader when/when-not against other state-setting siblings, so it is clear context without full 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 only cover the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds substantial behavior beyond that: the refusal path on 'stop', the fact that no session is created in that case, concurrent multi-session weighting, and the start_at clock-skew rule (>2 minutes ahead treated as now).

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 action and the verdict alphabet, then the failure protocol, then the concurrency rule, then the app/agent parameter triage. Dense and mostly waste-free, though the final sentence compresses several distinct concerns into one clause chain.

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 15-parameter tool with no output schema, the description does the work the missing output schema would: it documents the returned verdict and the agent's obligations for each. The unusual parameters and the concurrent-session model are also covered, leaving only self-evident ids to 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?

With 80% schema description coverage the baseline is 3, but the description adds real meaning by triaging three otherwise-confusing params: apps replaying a queued start pass op_id, session_id and start_at, while an interactive agent leaves all three out. It adds nothing for itemId/stepId/leverId/projectId/workplace, but those are covered by the schema.

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

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

States a specific verb and resource ('Start a session of work') plus the secondary effect ('if none is running, the timer') and names the concrete return values (ok | stop | plan_first). An agent can distinguish this from add_session/edit_session/stop_session without opening a schema.

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

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

Gives explicit branch handling: on 'stop' no session is created, relay the message, ask the user, and only re-call with override=true if the user insists. It also states the agent-vs-app calling rules. It does not, however, say when to prefer this over sibling tools like add_session or edit_session.

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, idempotentHint=false, openWorldHint=false. The description nonetheless adds real behavioral context: the timer keeps running for other sessions, the merge semantics for duplicate queued stops (earliest end wins, done wins, first summary kept), and the applied: ended|shortened|recorded return signal. This goes beyond the annotations.

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

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

Purpose and the session_id scoping rule are front-loaded, and every clause carries information. It is dense with long run-on sentences about offline merge ordering, but the content is substantive rather than filler.

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

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

For a mutation tool with 6 params and no output schema, the description covers the required inputs, the optional queued-delivery inputs, side effects on linked plan items, conflict/merge behavior, and the shape of the response. An agent has what it needs to call it correctly.

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

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

With schema coverage at 67%, the description meaningfully compensates: it explains that session_id comes from get_now and is required with op_id/end_at, that op_id and end_at are for offline-queued apps and should be omitted by interactive agents, and that outcome=done completes the linked plan item or path step — none of which the schema conveys.

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

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

States a specific verb and resource ('Stop a running session') and immediately scopes it with the summary/outcome inputs. It differentiates itself from siblings by naming edit_session as the tool to use for an already-ended session and by carving out its behavior against stop_timer/delete_session.

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

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

Explicit when-to-use: pass session_id from get_now, otherwise only this connection's session. Explicit when-not and alternative: 'without end_at or op_id it refuses a session that already ended: use edit_session for that.' It also says when each of end_at/op_id applies (queued offline apps).

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

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

Goes well beyond the annotations by disclosing real side effects: there is no paused state, resuming creates a brand-new session, and all running sessions are closed by this call. That concretely explains the destructive/irreversible semantics the annotations only flag abstractly.

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 core action and scope, then the state-model caveat, then the parameter/alternative guidance. No filler and nothing repeated from the schema or annotations.

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?

No output schema exists, yet the description states the return value (break length). Combined with the disclosed side effects, the alternative tool, and parameter persistence semantics, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is only 50% (summary is undocumented in the schema), and the description compensates by explaining that summary and outcome are persisted onto the sessions being closed. It also confirms the enum's default of partial indirectly via the schema, adding genuine meaning for the undocumented 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?

States a specific verb and resource (stop the timer) plus its scope: it also stops 'every running session with it'. It explicitly names the sibling stop_session, 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?

Gives a clear routing rule: pass summary/outcome here to save them on the closed sessions, or call stop_session first instead. That names the alternative and the condition that selects it, though it does not spell out the general when-not-to-use case (e.g. behavior when no timer is running).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description goes beyond that by enumerating the returned payload (minutes per area, classification, lever, sessions, gaps, overlaps, overrides), which is valuable since no output schema exists. It does not mention cost, pagination, or behavior for days with no data.

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 a compact enumeration; every token carries content. The colon-list style is dense but readable, with no filler or repetition.

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 carries the burden of describing the response and does so at a field-group level, which is enough for an agent to decide whether to call it. The only gap is the omitted-parameter default and empty-day behavior.

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

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

Schema coverage is 100% and the single 'date' parameter is fully documented there (YYYY-MM-DD, user timezone). The description adds nothing about the parameter, and since it is optional (0 required) it does not explain what happens when it is omitted (presumably today). 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?

Names a specific verb+resource ('summarize day') and enumerates exactly what the summary contains (wall/attention minutes per area, classification, lever, sessions, gaps, overlaps, overrides), so an agent knows this is a read of aggregated daily data. It does not explicitly distinguish itself from the sibling summarize_week, but the day/week scope split is inferable.

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, no prerequisites, and no mention of the sibling summarize_week as an alternative for multi-day rollups. Usage is only weakly implied by the resource name.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds useful behavioral content by disclosing the returned dimensions, but says nothing about pagination, permissions, or formatting. Given annotation coverage, a 3 is appropriate.

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 with the range constraint front-loaded and zero filler. It is compact and information-dense, though the fragmentary style slightly reduces immediate parseability.

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 enumeration of returned metrics ('goal share, hard share, area balance, overrides, streak, milestone pace') usefully compensates by telling the agent what it will get back. Combined with the fully documented single parameter and complete annotations, it is nearly complete; it only lacks explicit routing versus summarize_day.

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 single 'date' parameter is already documented ('any day of the week, default today'). The description reinforces the week range and partial-week behavior for the current week, but adds no syntax beyond the schema, so the baseline 3 applies.

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

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

The description is a noun-phrase content enumeration ('main-step days, goal share, hard share...') rather than a verb+resource statement; the action ('summarize') is carried only by the title/name. It is specific about what the week summary contains and implicitly contrasts with the day granularity via 'Monday to Sunday', but it never states the operation outright or names the summarize_day sibling.

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, no exclusion conditions, and no reference to the obvious alternative summarize_day. The weekly framing ('Monday to Sunday') implies the context, but the agent must infer it.

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