telo

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

Annotations already carry destructive=true and updates_are_not_idempotent, so the bar is lower, and the description still adds real context: the reason string is surfaced to the user in change history, and every change is undoable on the phone. That reversibility note materially softens what 'destructiveHint' would otherwise imply and is not derivable from the annotations. It doesn't say what happens when order, remove, and remove_marks are combined in one call.

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

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

Two sentences, front-loaded with the verbs, then the intent trigger, then the behavioral payoff — nothing redundant. No restating of the tool name or filler preamble.

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

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

An output schema exists and all four parameters are fully documented, so the description only needed to cover intent and side effects, which it does. The remaining gap is minor: it doesn't clarify interaction between simultaneous order/remove arguments or whether an omitted `remove` means 'no removals'.

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 ordering/preservation semantics of `order`, the max item limits, and the reason length cap are all already documented in the schema. The description's only added signal is that `reason` is user-visible, which the schema also states, so it meets the baseline without exceeding 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 three concrete operations (reorder cards, remove cards, remove marks) against the resource 'home cards', which an agent can match to a user intent like 'tidy my home'. It does not explicitly distinguish itself from close siblings such as edit_card or pin_card, so differentiation relies on the reader knowing those tools.

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

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

Gives a clear trigger condition — the user asking to set up or tidy their home — reinforced with a worked example ('set my home up for race week'). It stops short of naming when NOT to use it or pointing at alternatives for single-card changes (edit_card, pin_card).

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

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

Beyond the annotations, the description explains that cancellation is only a request requiring iPhone processing, that removal can happen during refresh or by opening the Planned workouts screen, that HealthKit results are not deleted, and that cancel_requested is not confirmation of removal. These details materially improve correct agent use and align with idempotentHint and destructiveHint.

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

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

The description is dense but well front-loaded: purpose first, then processing caveats, then workflow guidance. Every sentence adds operational or behavioral value without 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 cancellation tool with an output schema, the description covers the important behavioral caveats: asynchronous processing, HealthKit safety, confirmation semantics, idempotency, and the correct workflow for changing a plan. The remaining omission, where to get the id, is minor and partly covered by the single-parameter schema and sibling workout_plans.

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 one required id parameter and 0% schema description coverage, the description adds some meaning by indicating the id refers to the user's identified workout plan. However, it does not clarify where to obtain that id or explicitly connect it to workout_plans, so the parameter guidance remains minimal.

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: request cancellation of the identified workout plan. It also distinguishes the operation from changing a prescription by directing cancellation plus creation of a new plan, so an agent can tell it apart from create_workout_plan and workout_plans.

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

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

It gives clear context for when cancellation is appropriate and explicitly names the alternative workflow for changing a prescription: cancel the old plan and create a new one for review. It does not provide explicit when-not guidance or point to workout_plans as the likely source of the plan id.

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

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

Beyond the annotations (non-read-only, idempotent, non-destructive) it discloses the crucial behavioral truth: nothing is delivered to the Watch, first delivery requires a manual permission grant in the iPhone app, later auto-delivery is opt-in and opportunistic. It also warns that device capability validation can reject activities/goals/alerts before scheduling and forbids claiming the Watch received the plan.

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 dense and front-loaded with the most important fact (pending plan, not delivered) in the second clause, and most sentences carry unique constraints. It runs long as a single unbroken paragraph and repeats the pool_length_m display-only point that also appears in the schema, costing some concision.

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 deeply nested workout-definition tool with an output schema and full safety annotations, it covers the operational facts an agent needs: delivery model, permission flow, validation failure and retry semantics, platform requirement (watchOS 11+ for pool custom workouts), and where to verify outcomes.

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 67%, and the description fills the gap with meaning the schema cannot express: units are seconds/meters, scheduled_at must carry an explicit local UTC offset, step names describing reps/weights are instructions rather than native repetition goals, pool swimming must use activity=swimming with location=indoor, and pool_length_m is display-only because WorkoutKit has no setter. It also explains that pool_distance_with_time advances only when BOTH distance and time are satisfied.

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?

"Create one structured workout requested by the user, scheduled within the next 7 days" states a specific verb, resource and scope. It immediately distinguishes this from delivery/inspection siblings by saying it stores a pending plan rather than starting anything on the Watch, and it explicitly points to workout_plans for checking results.

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 triggering condition (user-requested workout, within 7 days), the alternative for verification (read workout_plans), how to handle rejection (retry with the SAME idempotency_key and payload), and the fallback path when background scheduling does not fire (review each plan manually).

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

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

The description carries substantial interpretation guidance the annotations cannot: an empty upload or re-sent old records are normal, old dates alone do not prove stalled sync, HealthKit read permissions are unknown, and a next_step message must be relayed to the user. It also states what is not returned (no account identifiers). This is exactly the caveat-level context that prevents an agent from drawing wrong conclusions from the 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?

The usage condition is front-loaded and nearly every clause carries decision-relevant content. The prose is dense and telegraphic in places (the history_import aside is compressed into one semicolon-chained sentence), which costs a little readability but not correctness.

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

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

An output schema exists, so describing the return values in detail is optional, yet the description frames how to read them. For a no-parameter, interpretive diagnostic tool the agent has everything needed to call it and to report results accurately.

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 no schema semantics the description could add. The description does not waste space restating an empty input, which is appropriate.

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

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

The description uses a specific verb ('Inspect') and precisely enumerates the returned evidence: last received upload batch, collection date ranges/counts, and per-metric coverage. It also negates a likely misreading ('Not a sync command'), which sharpens the purpose considerably. It does not explicitly differentiate itself from nearby siblings like report_gap or query_daily, 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?

It gives a clear trigger ('before health reviews or investigating missing data') and an explicit exclusion ('Not a sync command'). What it lacks is routing to the sibling that should be used instead for the excluded case, so the agent must infer the 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?

Beyond the annotations, the description discloses important non-obvious behavior: walking is excluded unless include_walking=true, missing workout days count as zero, workouts without usable zones contribute zero, coverage can be null, and results truncate at 500 rows. These are substantive operational details an agent would not know 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?

The description is front-loaded with the primary purpose, but it is a dense single paragraph containing formulas, edge cases, coverage rules, baseline rules, and truncation in quick succession. Most content earns its place, but the structure makes it harder to scan than a more segmented description 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?

Given the tool's complexity, six parameters, output schema, and combined training-load plus personal-baseline behavior, the description is highly complete. It covers formulas, defaults, missing-data handling, coverage semantics, baseline requirements, and row limits; an agent has enough information 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 description coverage is only 50%, but the description meaningfully compensates by explaining include_walking exclusion, max_hr override behavior, include_trimp legacy-object behavior, and the 30–60-day HRV baseline window with a minimum of 7 valid daily values. It does not explicitly explain from/to or baseline_days by parameter name, but the semantic intent is still clear.

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 this returns duration-based training workload metrics, TRIMP fields, and HRV/resting-HR baselines over a date range. It also distinguishes the metric from intensity-weighted TSS, but it does not name or differentiate itself from sibling tools such as list_metrics or query_daily.

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 defaults such as excluding walking, optional TRIMP output, and the 500-row warning. However, there is no explicit when-to-use guidance versus alternatives like list_metrics or query_daily, and no clear when-not-to-use statement.

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 state mutation, idempotency, and non-destructiveness, so the description's job is to add update semantics — and it does: "null removes an option" clarifies that explicit nulls strip configuration rather than leave it unchanged, which is the single most error-prone aspect of a partial-update tool. It still does not say that omitted fields are left untouched, nor whether edits are reversible, so a small gap remains.

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 resource and the editable surface, followed by the two rules an agent most needs (null semantics, id prerequisite). No filler or 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 an 11-parameter partial-update tool with an output schema (so return values need no explanation), the description covers the editable surface and the null convention well. The remaining shortfall is the undocumented "reason" parameter and unexplained style/window enum values, which the schema also leaves bare.

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 55% schema coverage, the description meaningfully compensates: it uses plain-language names for schema keys ("usual range" for baseline, "comparison" for compare_with) and generalizes null-as-removal across the nullable options. It leaves "reason" and "style"/"window" value meanings unaddressed, so it is not fully compensating.

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?

"Change one card" gives a specific verb and a scoped resource, then enumerates the editable facets (title, window, style, comparison, usual range, color, size, change_from, goal) so an agent can map intent to the tool. It does not explicitly contrast itself with the layout/pinning siblings (arrange_home, pin_card), which keeps it short of a 5.

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

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

"Call home first for ids" is a genuine prerequisite that tells the agent it must obtain card identifiers before invoking, and "Only when the user asks" is carried in the schema. However, there is no guidance on when to use edit_card versus arrange_home, pin_card, or home, so usage is implied rather than routed.

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), so the description rightly focuses on content scope and semantics. It adds genuinely useful context beyond annotations: that marks are user-authored life context to factor into interpretation, and that reading should precede editing. No mention of auth, limits, or paging, but those are minor for a zero-param read.

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 verb and resource list, and each subsequent sentence adds a distinct piece of guidance (interpretation, sequencing). No filler, though the resource enumeration partially overlaps with the title's framing of 'telo home'.

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 zero parameters, an output schema, and full annotation coverage, the definition supplies what the structured fields cannot: the meaning of marks and the read-before-edit rule. Only the scope of 'recent changes' is left unspecified, a small gap for a read 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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description adds no parameter guidance but none 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 ('Read') and names the concrete resources returned: cards on the home screen, dated marks, and recent changes. This clearly separates it from mutating siblings like edit_card or arrange_home, though the domain jargon ('telo home', 'cards') is only inferable from the title and siblings.

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

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

'Call before editing the home' gives explicit sequencing guidance relative to the editing siblings, and 'use them when interpreting their data' tells the agent what to do with marks. It stops short of naming the specific alternative tools (arrange_home, edit_card) or stating when not to call 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?

The description frames this as a pure discovery/read ("Lists ..."), yet the annotation declares readOnlyHint=false, which suggests the tool may not be side-effect free — the two signals pull in opposite directions. Aside from that, the description adds no behavior beyond annotations: no cost, caching, or latency note for a no-parameter call, and it does not clarify the freshness of the data range it reports.

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

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

Two sentences, zero waste: the first states output contents, the second states the invocation rule and the sibling it depends on. The key guidance (when to call) is front-loaded enough to be read in a single pass.

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

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

For a no-parameter discovery tool with an output schema, this is essentially complete — the agent knows what it returns and when to reach for it. The remaining gap is routing among the other metric-ish siblings (data_status, derived_metrics, sessions), which the description never mentions.

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 needs to disambiguate. It does usefully note that the call returns metric names, units, and data history depth, which is more than the empty 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?

"Lists the available health metrics, the unit of each one, and how far back the data goes" names a specific verb (lists) and resource (health metrics) and even previews the three fields returned, so an agent knows exactly what it gets. It does not distinguish itself from near-neighbours such as data_status or derived_metrics, which also sound like metric-discovery tools, so it stops short of full sibling differentiation.

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

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

It gives an explicit trigger and a named alternative: "Call this before query_daily if you do not know the exact metric names." That is a clear use condition tied to a concrete sibling. It lacks a when-not clause (e.g., skip it if names are already known, or use data_status for coverage/freshness questions), so it is 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 only declare the mutation/no-idempotency profile; the description adds real value by explaining the downstream effect — the mark appears on every chart spanning that date and is surfaced by home to later assistants. It does not mention that repeat calls create duplicate marks (idempotentHint=false) or how an existing mark is changed or removed, which is the remaining gap.

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

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

Two tight sentences: the first covers what is stored and where it appears, the second covers the evidentiary constraint. No filler, and the key restriction is front-loaded alongside the purpose.

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

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

An output schema exists, so return values need no explanation, and the description covers scope, persistence, and the user-stated-only rule for a simple three-parameter mutation. Only the duplicate-mark behavior and any edit/delete path are unaddressed, which is a minor omission for this complexity.

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 reinforces the date-versus-span distinction that maps to date/end_date, clarifying that a span is one note ('a sick week') rather than two marks. The text parameter's meaning is already documented in the schema, so this is incremental but useful reinforcement rather than redundant restatement.

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 action and resource: keeping a short user-stated note on a date or span that renders on every telo chart covering that date. That is enough to separate it from siblings like arrange_home, home, and report_gap, though it never names an alternative to contrast with.

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

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

Gives a clear trigger (the user told you about illness, travel, new training, new shoes) and an explicit exclusion ('Only for facts the user stated, never your inference'). It does not discuss overlap with nearby tools such as report_gap, so the routing guidance stops just short of the top mark.

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 and openWorldHint=false, so the write-but-non-destructive profile is structured. The description adds genuinely new behavior: the card is live and refreshes on each sync, defaults to a per-category color, and half-size cards pair into a row with tap-for-detail. It does not say what happens if the same metric is pinned twice (relevant given idempotentHint=false) or whether a card can be removed.

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 purpose, then usage gating, then an option-by-option tour, which is a sensible order for a 13-parameter tool. The single dense paragraph is run-on in places ("size=half puts two consecutive half cards side by side…") and could be split for scanability, but almost every clause carries information.

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

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

Output schema exists, so return values need no explanation, and the description covers the creation semantics, liveness, and the majority of meaningful options. For a card-creation mutation it is nearly complete; the omissions are the window/position/title parameters and duplicate-pin 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?

With 13 parameters at 69% schema coverage, the description earns credit for explaining semantics the schema only names: baseline=personal as mean ± 1 SD over the 60 days before the last week, change_from's three comparison bases, size=half pairing behavior, and display=pace_km converting m/s to min/km. It leaves window, position and title entirely unexplained, which are three of the uncovered parameters.

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

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

"Put a live chart on the user's telo iPhone home" names a concrete verb and destination, and "the card keeps updating with each sync" clarifies what kind of object is created. It is distinguishable from pin_countdown and edit_card by implication (chart vs countdown vs editing), but the siblings are never named 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?

"Only when the user asks to pin, save, show or keep something on telo" gives a clear positive trigger plus an exclusion, and per-parameter conditions ("goal only when the user stated one", "color only when the user asks", "Always pass the user's question") are spelled out. No routing guidance toward siblings such as pin_countdown or edit_card, which is the main gap.

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 disclose readOnlyHint=false, destructiveHint=false, openWorldHint=false and notably idempotentHint=false; the description adds nothing about what that non-idempotency means in practice (e.g., calling twice yields two cards). It also omits placement/overwrite behavior and what a successful pin changes on the home, spending its second sentence on flavor ("telo counts days; it never judges them") instead.

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

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

The purpose is front-loaded in the first clause, which is good, but the trailing aphorism consumes roughly half the text without informing an invocation decision. For a two-sentence description, one sentence is essentially decorative.

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

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

An output schema exists and the input schema is largely self-documenting, so return values and most field semantics need not be restated. However, for a 7-parameter, non-idempotent creation tool, the description should at minimum address duplicate-pin behavior and how this differs from pin_card, and it does neither.

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 71% and most meaningful parameters (size, color, title, detail, question) already carry inline descriptions, so the baseline is 3. The description contributes only the weak implication that the date comes from the user's own naming rather than being invented; it adds no format, constraint, or default information beyond the schema.

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

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

The description uses a specific verb-plus-resource ("Add a countdown ... to their telo home") and gives concrete examples of the date being counted down to (a race, a trip, a test). It is clear what the tool creates, but it never names the obviously adjacent sibling pin_card, so an agent must infer the boundary itself.

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 such as pin_card or edit_card, despite those being plausible options for the same home surface. The examples of countdown subjects hint at the use case but do not tell the agent which tool to pick.

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

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

The description adds substantial context beyond the annotations: a hard 500-row limit, truncation handling, the rule that missing buckets produce no row rather than zero, and the non-ISO SQLite %Y-W%W week labeling with a pointer to period_start/end. The annotations declare readOnlyHint=false for what reads as a pure retrieval tool; the description never addresses side effects, so it neither confirms nor contradicts that hint, but the operational detail it does supply is genuinely valuable.

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 purpose and packs real information, but it reads as a dense run-on of caveats, with several sentences devoted to output-field semantics. The clause 'Units and aggregation methods are kept separate' is opaque and does little work for the reader.

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

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

The tool ships an output schema, so much of the text explaining aggregation, daily_min/max, days_present, and days_expected restates what structured output already conveys, while the required metrics identifiers and the from/to clipping semantics go unexplained. Truncation and missing-data behavior are well covered, making it adequate but unevenly complete for a four-parameter query tool.

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

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

Schema description coverage is 0% across four parameters, so the description must carry the load and largely does not. It refers to 'aggregation' and 'period_start/end', which are not parameter names (the parameters are granularity, from, to, metrics), leaving the required metrics array — which metric identifiers are valid — and the day/week/month granularity semantics undocumented. Only the week/month aggregation behavior is loosely implied.

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

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

The opening sentence establishes the resource and scope precisely: daily metric records, or week/month aggregates of them. The verb is implicit (retrieval is implied by 'Query'), and there is no differentiation from siblings like list_metrics or derived_metrics, which an agent could easily confuse with this 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?

It gives solid operational guidance for one scenario — what to do when the 500-row limit truncates results (discard and re-query smaller aligned ranges, or fewer metrics) — and warns against combining partial averages without weighting by days_present. However, it never says when to prefer this tool over list_metrics or derived_metrics, leaving the main selection decision 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 declare this is a non-read-only, non-destructive, non-open-world write, and the description adds genuinely useful context beyond that: the note goes to the telo team rather than the user's workspace, and the agent must not promise the feature will be built. It does not address duplicate submissions (idempotentHint=false implies repeat calls create separate reports), which would have been the final piece of behavioral context.

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

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

Three sentences, front-loaded with the trigger condition, then the payload instructions, then the user-facing follow-up, with the exclusion as a final guard clause. No sentence is redundant and the ordering matches the order in which an agent needs the 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?

The tool is simple (four flat parameters, output schema present so return values need no explanation), and the description covers trigger conditions, content guidance for all three required fields, and the required user communication. Nothing an agent needs to call this 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 100%, so the baseline would be 3, but the description adds real meaning by instructing that `request` be captured "in their words" and that `tried` and `missing` be supplied — clarifying the intended content and fidelity of each field rather than just naming them. It stops short of explaining how to choose between the `area` enum values, though the schema's own enum descriptions handle that.

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

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

The description opens with a specific trigger ("Call when the user asked for something telo cannot do with the tools here") and enumerates the concrete gap categories — home chart/layout, missing metric, missing data, unanswerable question — which map cleanly onto the `area` enum. It is unmistakably a gap-reporting tool and cannot be confused with arrange_home, list_metrics, or the query tools.

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

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

It states exactly when to call, gives four illustrative trigger cases, and closes with an explicit exclusion: "Not for questions you can answer by reading their data." It even prescribes the follow-up message to the user, so the agent knows both the entry condition and the post-call behavior.

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?

Without strong annotation help (readOnlyHint=false and destructiveHint=false tell the agent little about a retrieval-shaped tool), the description carries real weight: inclusive boundaries, boundary weeks covering only requested dates, coverage counts distinguishing missing data from zero, and local UTC offsets on timestamps. It does not describe pagination, result ordering, or what the response envelope looks like, but the output schema covers returns.

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 scope, then constraint-by-constraint detail in five tight sentences with no filler. Some sentences are telegraphic to the point of ambiguity ('Distance and zone coverage counts distinguish missing data from zero' requires unpacking), but nothing is redundant.

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

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

An output schema exists, so return values need no explanation, and the description instead covers the non-obvious semantics an agent would otherwise get wrong: inclusive range, week grouping boundaries, missing-vs-zero coverage, and timezone handling. For a 6-parameter read tool this is sufficient 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?

Schema coverage is only 17% (only max_hr is documented), so the description must compensate, and it largely does: it resolves the activity enum aliases (run/bike/swim or running/cycling/swimming), explains that granularity=week groups by Monday date and modality while summing duration, distance and HR-zone seconds, and states that activity/granularity only apply with kind=workout. Gaps remain on the default granularity and on what happens if activity is passed with kind=sleep.

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 and scope: 'Sleep nights or workouts within an inclusive date range', and names kind=workout as the mode that enables filters and weekly grouping. That distinguishes it from workout_detail and query_daily well enough, though the differentiation is indirect (via 'max_hr uses the same definition as workout_detail') rather than explicit.

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 one hard routing rule: 'Filters and weekly grouping require kind=workout', which tells the agent when activity/granularity/max_hr are valid. It never says when to pick this over query_daily or workout_detail, and gives no guidance on when kind=sleep is preferable to another daily tool.

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

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

The description describes a read-only retrieval of workout detail, but the annotations declare readOnlyHint=false. That is a direct conflict on the tool's side-effect profile, and the description does not reconcile it. Otherwise it is rich, but the contradiction forces a 1.

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 purpose, but the remainder is a dense single paragraph of implementation edge cases (R2 fallback, continuity P90, swimming wall gaps) that is hard to scan. Many details earn their place for interpretation, but the lack of structure and length push it below concise.

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

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

Given the tool's complexity (series, events, zones, continuity, pagination) and the presence of an output schema, the description covers availability, expiry, sync prerequisites, zone estimation, event normalization, continuity rules, and pagination independently. Nothing material for correct invocation appears 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 86% and the schema already documents uuid, max_hr, offset, metrics, event_offset, and wall_tolerance_s in detail. The description adds narrative around wall_tolerance_s and max_hr but largely restates what the schema provides; limit remains undocumented.

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

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

The opening sentence names the resource (workout detail) and the identifier source (UUID from sessions), and the body enumerates the exact payload components. An agent can distinguish it from sessions (list) and derived_metrics (aggregates) without opening the schema.

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

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

It implies the workflow by saying the UUID comes from sessions and explains pagination via next_offset/next_event_offset, but it never explicitly states when to choose this over derived_metrics or query_daily, nor when not to use it. The metrics: [] note is helpful invocation guidance but not tool-selection 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?

Goes well beyond the readOnly/idempotent annotations by decoding the delivery-state machine (pending, scheduled, cancel_requested) and warning that 'scheduled' does not confirm Watch delivery. It also discloses negative-inference traps (recorded_workout=null is not proof of a skip; a linked recording is not proof of full interval completion) and that the server cannot see automatic scheduling state or background execution time.

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 and scope are front-loaded in the first clause, and nearly every sentence carries distinct operational information (state meanings, caveats, fallback). It is dense and somewhat run-on in the middle, but no sentence 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?

An output schema exists, so return-shape explanation is not needed, and annotations cover the safety profile. The description fills the remaining gaps an agent needs: delivery-state interpretation, the uncertainty around missing or linked recordings, and the truncation behavior — appropriate depth for a read-only listing 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% and the parameter already documents 'omit for the latest 50 plans', so the baseline is 3. The description adds meaning by telling the agent where the id value comes from (a plan's uuid) and how to recover from truncation by querying a known id.

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 ('Read the latest 50 planned workouts, or one by id') plus the returned fields (prescription, delivery state, linked HealthKit workout). It also distinguishes itself from the sibling workout_detail by positioning itself as the discovery/listing step that supplies the uuid.

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 routing: use the returned uuid with workout_detail for analysis, ask for perceived effort, and query a known id if results are truncated. It does not state explicit when-not conditions versus siblings like data_status or session tools, but the primary follow-up path is spelled out.

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