Nolio

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

Annotations only declare readOnly=false, destructive=false, openWorld=false; the description goes well beyond by disclosing that no content overrides are possible, that audiences are mutually exclusive (athletes XOR group, omit for self), that bulk expansion must be routed through a dry-run/confirm batch rather than a loop, and that conflicts should be surfaced first. That is the kind of rate-limit/confirmation and side-effect context the annotations cannot carry.

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

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

Front-loaded correctly: the action and app analogy come first, then alternatives, then the bulk-work protocol. The bulk paragraph is dense and contains a small artifact ("POST batch/ "), and slightly crowds out the core call pattern, but every sentence does carry instructions an agent would otherwise get wrong.

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

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

For a 7-parameter tool with a nested recurrence object and no output schema, the description covers preconditions, audience targeting, post-call adjustment path and the escalation route for bulk changes. Nothing an agent needs in order to invoke 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% and the schema already documents mutual exclusions, date resolution and recurrence, so the description is largely restating it. It still adds one genuinely new parameter-level fact — that no content-override parameters exist on this call — which prevents an agent from hunting for a title or override field.

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 ("Schedule a library template on the calendar") and anchors it with an app analogy ("same gesture as dragging a template onto the calendar"), which instantly fixes the mental model. It explicitly separates itself from create_planned_training ("do not copy its content manually via create"), so an agent can pick it over siblings 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 when-to-use (schedule an existing library template), when-not (do not use it to recreate content via create), and the follow-up path ("call update_planned_training afterwards" to adjust). It also names the operational alternative for bulk work — nolio_api_write with dry_run=true and a confirm_token — plus a precondition read via get_calendar mode='planned'.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write, so the description focuses on valuable extras: default type inheritance from the parent, the one-level nesting constraint, the requirement to pass `team` when creating under a club folder, and that club libraries only accept 'event' and 'plan' types. Those are real behavioral constraints not present in 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?

Front-loaded with the purpose, then a compact per-parameter breakdown. The backtick-led bullet format is slightly awkward in prose but each sentence carries concrete information 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?

Covers what is needed to call the tool correctly and even points to the follow-up (filing templates via create_training_frame/update_training_frame with `category`). With an output schema present, return values need not be explained; only minor gaps like duplicate-name behavior remain.

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 full burden and does so: it defines the meaning and allowed values of `type`, the source of `parent` handles (list_library_categories) and the nesting limit, and the source of `team` handles (list_athletes) plus its restrictions. Only `name` is left implicit, which is self-evident.

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

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

States a specific verb and resource ('Create a folder in your template library, or in a club's library') and scopes it beyond a single library. It is clearly distinguishable from siblings like update_library_category or list_library_categories.

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 the routing decisions an agent actually faces: root vs sub-folder via `parent`, personal vs club library via `team`, and the one-level nesting rule. It stops short of naming when to prefer update_library_category over creating a new folder, so no explicit exclusion is given.

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

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

Annotations already mark this as a non-read-only, non-destructive write operation; the description adds valuable behavioral detail beyond that, including overlap refusal for cycles, field refusal for invalid fields, name exceptions for template questionnaires, description acceptance rules, and undo semantics. No contradiction with 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 description is long but justified by 23 parameters and zero schema descriptions. It is front-loaded with key constraints and organized by event type, and every section provides actionable information rather than restating the name or schema.

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

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

Given the tool's complexity, 0% schema description coverage, and the presence of an output schema, the description is complete enough to call the tool correctly. It covers audience rules, conditional requirements, per-type fields, ID sources, refusal conditions, and undo 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 description coverage is 0%, so the description carries the full parameter burden. It thoroughly documents all 23 parameters by event type, including requiredness, formats, accepted enum-like values, ID prefixes, question structures, and type-specific conditional rules.

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: planning a competition, cycle, note, or questionnaire on a planned calendar. It explicitly distinguishes itself from the closest sibling, create_planned_training, which handles planned workouts.

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 routing guidance to create_planned_training for workouts, defines the athlete-vs-group audience rules, lists required fields by event type, names lookup tools for IDs, and states undo behavior via delete_event. An agent can decide when and how to use it without 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses the return shape (normalized event plus human-readable summary to verify against the request) and a batching/throttle behavior with confirmation flow. It stops short of stating permission requirements or exactly what a dry_run failure set looks like, keeping it below a 5.

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

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

Purpose and required fields are front-loaded and the batching escape hatch is prominent, but the closing paragraph about A-race goals, cycles, and notes describes plan-building philosophy rather than how to invoke this specific tool, which dilutes the focus somewhat.

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 22-parameter tool with heavy nested structured content and no output schema, the definition covers targeting, portability of targets, the null/patch semantics caveat (workout to null does not null derived totals), and return verification — enough for an agent to call it correctly without guessing.

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 100% schema coverage the schema already documents parameters, but the description adds genuine cross-field meaning: the audience exclusivity, the portability of targets (zone/% resolved per athlete), and a fallback rule that unexpressible intent goes in a node comment rather than being approximated into another field.

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 first sentence gives a specific verb (create) plus resource (planned training workout) and enumerates all three target audiences (athletes, group, self), so its scope against create_planned_event/update_planned_training is clear without opening schemas. Required fields are stated up front.

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

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

It gives explicit when/when-not rules: at most one of athletes/group, omit both for self, and a hard escape hatch — if a request expands beyond 3 operations, do not loop, use nolio_api_write with dry_run=true and a confirm_token. It also prescribes a pre-read via get_calendar before scheduling to surface conflicts.

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 say it is a non-read-only, non-destructive, closed-world write; the description adds what the annotations cannot: zone and % targets are stored portable and resolved per athlete at apply time, the response is a normalized template plus a human-readable summary, and multi-write batches require a plain-language recap and user approval before re-sending. Nothing here contradicts readOnlyHint=false.

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 template-vs-scheduled distinction are front-loaded, and the denser batch-protocol paragraph is placed last where it belongs. It is tightly written but the middle sentences stack three separate rules (portability, comment fallback, batch threshold) into one block, costing a little scannability.

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

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

For an 18-parameter tool with deep nested workout nodes and no output schema, the description covers creation scope, library targeting, the portability contract that governs every target, the escalation path for bulk operations, and the return shape. The remaining details (field-level formats, enum values, required category) are fully documented in 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?

Schema coverage is 100%, so the schema already carries per-parameter meaning (team defaulting to personal, category being required for library visibility, sport/zone/metric quoting rules). The description still adds cross-cutting semantics: the portability model for zone/% targets and the instruction to route unexpressible intent into node comments rather than approximate it into another field. Incremental, but real value 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 opens with a specific verb and resource ("Create a reusable workout template in the coach's library") and immediately scopes it against the calendar-based siblings: "A template has no date and no athletes — schedule it later with apply_training_frame." An agent can distinguish this from create_planned_training or update_training_frame 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?

Explicit routing in both directions: use apply_training_frame later to schedule, and if the request expands past three writes, do not loop this tool — batch through nolio_api_write with dry_run=true and a confirm_token. It also gives a fallback rule for details the schema cannot express (put them in a node comment, never approximate or drop). This is unusually complete when-to-use 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 declare destructiveHint=true, but the description adds what the annotations cannot: deleting an applied plan or plan template destroys its whole content, the user must confirm first, and bulk paths should be batched/dry-run. It also discloses the two-step confirm parameter's conversational precondition.

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 the id-only guidance, then the destructive/confirmation constraints and batching rules. Dense but each sentence adds operational value; the long parenthetical entity enumeration is slightly bulky.

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?

Covers destruction scope, confirmation, batching, and recurrence handling — the key risks for a destructive multi-param delete. It does not mention the undo_deletion/list_recent_deletions siblings as recovery paths, which would round out the operational 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 coverage is 100%, so baseline is 3. The description goes beyond it by explaining that the id alone identifies type and that extra scoping params should be omitted, plus constraining recurrence_action to planned events, though it leaves the plan/group/athlete disambiguation to 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 (delete) with an enumerated set of resources: one event from the planned/realized calendar or one library template, listing the concrete entity types (workout, note, quiz, competition, message, exercise, plan). This clearly separates it from siblings such as update_planned_event or create_library_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?

Gives explicit when/when-not rules: 'one event per call, never in a loop', several deletions go in one POST batch after a dry run, recurrence_action is only for planned events, and more than 3 writes require listing targets and explicit confirmation. An agent has a complete routing decision without 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?

Goes well beyond readOnlyHint: discloses that a single unreadable type fails the whole call with `failed`, that has_more[type]=true means an incomplete window and how to paginate without silently switching calendars, that planned mode costs five API requests vs two against the quota, and that an uncoached athlete is refused 403 and an unmanaged group 404. Also flags description truncation at 250 characters.

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 mode semantics are front-loaded and most sentences carry operational payload, but the pagination paragraph and the return-value tour run long and restate some ground the output schema already covers. Dense rather than padded, though not maximally tight.

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, two-mode, paginated, quota-metered read tool this covers the full decision surface: what each mode returns, failure semantics, refusal codes, pagination continuity rules, and cross-references to the tools that hold the data this one omits.

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 11 parameters, so the description must carry everything and does: it documents every parameter, including non-obvious defaults (limit 100 with a window / 10 without in planned, 10 always in real), the usr_/grp_ handle formats, the interaction between `types` and `starting_after`, and which flags are mode-restricted.

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+resource plus three scoping variants ('your own, a managed athlete's with `athlete`, or a group's with `group`'), then splits the resource into the 'real' vs 'planned' palettes and enumerates the types each returns. This lets an agent separate it from get_planned_training, list_planned_trainings and get_training 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?

Explicit routing: 'Read it before scheduling anything on a period', 'Read a planned workout with get_planned_training for its full text', and 'For a whole period, prefer the `zones_duration_*` chart of get_stats_chart' instead of time_in_zones. It also states negative constraints ('Never pass it with `athlete`', group is planned mode only) and when to drop the heavy flags.

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 establish that this is a read-only, non-destructive, closed-world operation. The description adds useful behavioral detail beyond annotations: it returns the operation plus referenced component schemas and accepts paths with or without the /api/v2 prefix.

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 and compact: purpose first, usage sequencing second, parameter notes third. Every sentence adds actionable information 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?

An output schema exists, so return-value explanation is not strictly required, but the description still summarizes what is returned. Combined with its usage sequencing and path/method guidance, it gives an agent enough context to invoke the tool 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 0%, so the description carries the parameter burden. It explains that path identifies the endpoint and may include or omit the /api/v2 prefix, and that method is the HTTP verb, though it does not mention the default method or accepted verb values.

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 and resource: get the exact request/response schema of one API v2 endpoint. It clearly distinguishes the tool from search_nolio_api_docs and the generic nolio_api_read/nolio_api_write calls by framing it as the schema-lookup step between search and execution.

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

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

It gives explicit sequencing: call this after search_nolio_api_docs to learn how to shape a nolio_api_read or nolio_api_write call. It names the relevant sibling tools, though it does not state when not to use it or what to do if the endpoint schema cannot be found.

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 it read-only and non-destructive, and the description adds substantial behavior: returned writable/read-only fields, revision as an optimistic-concurrency token, summary units, target resolved values ignored on write, and note steps not sent to watches. That is meaningful detail beyond annotations and does not contradict them.

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 front-loads the purpose and every sentence carries operational detail, but the description is dense and packs multiple field/update semantics into semicolon-heavy prose. Still, little is redundant given the absence of an output schema.

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

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

With no output schema, the description supplies the missing return-value guidance: writable fields, read-only fields to omit from patches, revision token, summary text, and note-step handling. That is complete enough for an agent to read and feed the event into an update call.

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

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

Schema description coverage is 100%, so all five inputs are documented in the schema, including id, group/athlete, recurrence_action, and with_description_html. The description adds semantics for returned fields like summary/revision rather than additional input-parameter meaning, so baseline 3 applies.

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

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

The first sentence states a specific verb and resource ('Read a planned training workout') and the required id in the schema makes the single-workout scope clear. It also contrasts its return shape with update_planned_training, though it does not explicitly name list_planned_trainings as the alternative for discovery.

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 explains the round-trip pattern with update_planned_training and warns to request description_html before changing an existing description, which gives useful context. However, it never states when to choose this over list_planned_trainings or other read siblings, nor when not to use it.

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

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

Annotations already declare readOnly/openWorld/destructive=false, so safety is covered; the description adds genuinely non-obvious behavior — that a call with no `category` returns no records at all but a catalog in `windows`. It also discloses the `top` cap of 10 and the unit/format conventions for pace. It does not explain anything about date scoping or the `athlete` parameter, which is the remaining behavioral 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?

Front-loaded with purpose, then the two-step workflow, then per-parameter notes — a sensible order for an agent. Density is high and each parameter line earns its place. The pace-formatting aside (238 s/km is 3:58 per km) is useful but is presentation advice sitting in a tool definition, slightly padding the tail.

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 detail is rightly omitted, and the one non-obvious return case (empty call yields the catalog) is covered. For an 8-parameter analytics tool with a zero-coverage schema, the undocumented `athlete` and date-range parameters are the notable omissions — particularly `athlete`, given list_athletes is a sibling and multi-athlete scoping is ambiguous.

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 coverage the description carries the full burden, and it mostly delivers: it enumerates the six `category` codes with their units, gives both legal `axis` values with meaning, states that `windows` are seconds or metres and must come from the catalog, and caps `top` at 10. Three of eight parameters — `athlete`, `date_from`, `date_to` — receive no mention at all, so it stops short of full compensation.

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-plus-resource ('Read personal records') and immediately defines the resource precisely: best power, pace, heart rate, torque, vertical speed or cadence held over a duration or a distance. That is distinguishable at a glance from every sibling (get_stats_chart, get_training_load, list_metrics), none of which return all-time bests.

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 prescribes an explicit call sequence: invoke without `category` first to get the category/window catalog, then read records with a `category`. It also names two prerequisites by sibling tool ('windows ... taken from the catalog only', 'sports: spt_… handles from list_sports'), so the agent knows where dependency values come from.

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 read-only annotations, the description discloses important behavioral details: default date window, athlete/sport scoping, return shape, count-chart inclusion rules, null RPE handling, tag counting, and how competitions affect counts. These are exactly the edge cases an agent needs before invoking the tool.

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

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

The description is dense but well structured: purpose first, then parameter semantics, then return and count-chart behavior. Every sentence adds operational value for a complex stats tool, with no obvious repetition or 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?

Although an output schema exists, the description adds necessary statistical interpretation around rows, totals, and count-chart denominators. Combined with the annotations and schema, an agent has enough information to call the tool correctly across the documented chart types.

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 covers all five parameters: chart id source and examples, date format and default range, athlete handle semantics, and sport catalog filtering, leaving no required parameter ambiguous.

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: read one statistics breakdown aggregated over a date window. It also distinguishes the tool from list_stats_charts by treating that sibling as the source of chart ids, so an agent can tell what this tool does and what it does not do.

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 explicitly routes chart-id discovery to list_stats_charts and explains the pattern for month-by-month evolution: call several sub-windows and compare. It lacks explicit when-not guidance or named alternatives for other stats-style questions, so it is clear but not fully exhaustive.

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

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

With readOnlyHint already declared, the description still adds substantial behavioral context unobtainable elsewhere: connector terms may withhold device laps, in which case only Nolio-drawn laps arrive with null stats and laps_restriction explains why; file-less workouts return available: false; unheld curves surface in unknown_streams. This is exactly the kind of edge-case disclosure annotations cannot carry.

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 before any parameter talk, and nearly every sentence carries operational detail. It is long and the exhaustive roster of device-specific curve types is the one passage that could be compressed without losing call-relevant 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 seven-parameter read tool with rich optional payloads, the description covers id provenance, optionality, sampling math, windowing semantics, and failure modes. With an output schema present the description did not need to explain return values, yet the returned-field references (laps_restriction, other_streams, unknown_streams, every_nth_sample) are precisely the ones an agent needs to interpret a call.

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

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

Schema description coverage is 0%, so the description must carry all semantic weight, and it does: id is the trn_/cmp_ handle, athlete is the usr_ handle for managed athletes, laps toggles device-then-Nolio lap inclusion, streams enumerates valid curve keys, max_points has a default and a 6000-point aggregate cap, and from_index/to_index are inclusive windows tied to a lap's start_index/end_index. Every parameter gets meaning the bare schema lacks.

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 first sentence names a specific verb and resource (read one completed workout or race) and enumerates the exact payload it returns: duration, distance, load, heart rate, power, debrief, plus optional laps and sensor curves. That scope cleanly separates it from siblings like get_planned_training, review_training, and get_calendar.

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 routes the agent to a specific sibling for the id ('a row returned by get_calendar(mode=\'real\')') and gives an explicit efficiency rule ('Ask only for the curves the question needs'). It does not, however, say when to prefer review_training or get_records over this tool, so there is no explicit exclusion set.

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 far beyond the readOnly/non-destructive annotations: it enumerates which returned fields are read-only, explains that unchanged fields sent back are no-ops, that 'resolved' target values are ignored on write, that 'summary' is in the caller's units, and that 'revision' is the concurrency token. It also discloses domain semantics for note steps that never reach watches.

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 front-loaded, with the round-trip contract stated first. Some sentences are overloaded with parenthetical field lists and an ellipsis-truncated enumeration, which slightly blurs an otherwise efficient definition.

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

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

There is no output schema, so the description carries the full burden of explaining the return value — and it does: writable fields, node ids, read-only fields, revision token, summary units, and the note-step edge case. An agent can consume and round-trip the result without further documentation.

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 parameters are fully documented in the schema, including the HTML-description caveat. The description adds no additional meaning about 'id' or 'with_description_html' — its extra detail concerns return fields, not inputs — so the baseline 3 applies.

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

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

States a specific verb and resource: read a library workout template, specifically in the 'curated' form, which separates it from raw training reads. It frames the round-trip relationship with update_training_frame, but never distinguishes itself from sibling readers like get_training, get_planned_training, or list_training_frames.

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?

Embeds clear usage context: read this to obtain the exact payload update_training_frame expects, pass 'revision' back for optimistic concurrency, and omit read-only fields from a patch. It stops short of explicit when-not-to-use guidance or naming the sibling reader that would apply to non-library or planned workouts.

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/non-destructive, so the description focuses on behavior beyond safety: server-computed curve requiring the athlete's own PMC time constants, default windowing, and that real is bounded to today. Doesn't cover output shape, but 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?

Front-loaded purpose sentence followed by per-parameter blocks and a return-field glossary. Every sentence adds information; the PMC explanation justifies why the curve isn't recomputed client-side.

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

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

For a 4-param read tool with an output schema and annotations, the description covers the semantic distinctions (real vs planned, own vs managed athlete, date windowing) and explains what each returned field means, which the output schema alone wouldn't 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?

Schema coverage is 0%, so the description carries the full burden and does: documents mode values and defaults, date format 'YYYY-MM-DD' with default 90 days, and the usr_… handle format for athlete sourced from list_athletes. This compensates fully for the bare 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 (read) and resource (training-load curve, Coggan fitness/fatigue/form) and names the metric families it returns. It's distinguishable from siblings like get_stats_chart and get_training by naming the concrete curve concept.

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 explains the two temporal halves: 'real' (realized curve, bounded to today, default) vs 'planned' (forward projection after today), with the rule 'ask for the one the question is about'. Also tells when to omit athlete (read your own) and when to omit dates (default 90-day window).

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 readOnlyHint=true/destructiveHint=false with real operational facts: archived athletes are absent and unreadable, groups expose a `parent` and already aggregate their sub-groups' athletes so counts must not be summed, and athletes with has_api_access:false must be reported plainly and not planned for. These are exactly the traps an agent would otherwise fall into.

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

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

Front-loaded with what is returned and the id formats, then layered with the caveats. It is dense and the group/parent sentence is long, but every sentence carries non-obvious 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?

There is no output schema, yet the description describes the return shape (athlete ids, groups with their athletes and optional `parent`) and the edge cases (archived athletes, has_api_access:false). For a zero-required-parameter read tool, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% and the schema already explains `q`, so baseline is 3; the description adds that matching is case- and accent-insensitive, that it matches athlete OR group names, and that omitting `q` returns the full roster. That is genuine added meaning beyond the schema text.

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

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

States a specific verb and resource and immediately defines the scope: athletes (usr_…), groups (grp_…), and teams (team_…). It also names the downstream purpose (targeting), so an agent can tell this apart from sibling list tools like list_athlete_subscriptions or list_sports 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 invocation guidance: 'Pass `q` to filter by name ... bare call = the full roster', and the ids are meant to be cited verbatim rather than guessed. It doesn't name a competing sibling tool or state when-not-to-use, so it stops short of the 5 bar.

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 readOnlyHint it discloses the visibility rule that determines the result set (who you can see) and the exclusion of ended subscriptions, plus the semantics of date_end when suspended. 'Read-only' restates the annotation, and pagination/ordering behavior behind `limit` is not described, so it falls just short of full transparency.

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, scope and exclusion before the per-parameter notes, and each sentence carries information. It runs long for a two-parameter list tool, and the status enum recitation is verbose given an output schema exists.

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 annotations covering safety and an output schema covering return shape, the description supplies everything else an agent needs: whose subscriptions appear, what is filtered out, where to go instead, and how to use both parameters.

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%, so the description carries the load and largely does: `athlete` is explained as a usr_… handle sourced from list_athletes, with the omit-to-list-all default spelled out. `limit` is only glossed as 'max rows' with no default value, maximum, or paging cursor mentioned.

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 precise verb+resource and immediately parenthesizes the domain meaning ('a coach billing an athlete monthly via Stripe'), which no sibling tool covers. It is clearly distinguishable from list_athletes, list_my_invoices and the generic nolio_api_read.

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 defines the returned scope (subscriptions you bill as a coach, plus your own when billed as an athlete) and states the exclusion — ended subscriptions are not listed. It then names the alternative route for that excluded case ('read billing/payments/ with nolio_api_read'), which is exactly the when-not/alternative guidance an agent needs.

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

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

Annotations already establish readOnly/non-destructive/closed-world, but the description adds genuinely non-obvious behavior: visibility rules (assistant-only teams are excluded), the scope taxonomy (self/team/nolio), the is_nolio read-only flag, and the fallback-with-hint matching mode. This is exactly the kind of context annotations cannot convey.

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 corpus scope before result shape and edge-case handling, and every clause carries information. It is a dense single paragraph with heavy parentheticals, which makes it slightly harder to scan than a segmented form 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?

There is no output schema, and the description compensates by enumerating the returned fields (id, name, type, is_load, laterality, scope, is_nolio) and explaining the laterality enum inline. Combined with the fallback and not-found guidance, an agent has everything needed to call this correctly and interpret the results.

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 already documents query (name/fragment, FR or EN), type enum, and is_load, so baseline is 3. The description adds real value on top by framing query as a name-based disambiguation step with word-level fallback semantics, which the schema does not state.

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 (search exercises by name) and precisely delimits the corpus: own exercises, visible team libraries (explicitly excluding teams where the user is only an assistant), and the shared Nolio global library. That scope language also differentiates it from siblings like list_library_categories or get_training, which deal with adjacent but 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?

Gives explicit when-to-use and when-not rules: the search is 'the disambiguation step, never guess an id', and if nothing is found the agent must tell the user and propose creation rather than invent an exercise. It also documents the word-level fallback path so the agent knows what a miss actually means before acting.

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 read-only annotations, the description discloses important behavior: folders are grouped by owner, `nolio` folders are listed only for organisation and cannot be used, `event` folders contain specific template kinds, and scheduled messages only land on the planned calendar. It also explains the `parent` field and that sub-folder names can repeat across parents.

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 and nearly every sentence carries operational guidance. It is dense and parenthetical-heavy, but the length is justified by the ownership and filing constraints an agent must understand.

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 listing tool with no output schema, the description supplies the missing context an agent needs: owner grouping, `parent` semantics, folder id usage, search behavior, and filing restrictions. Nothing essential about how to interpret the listing is omitted.

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 adds useful meaning for the `type` parameter by elaborating what each library section contains and clarifying that `event` folders include competitions, notes, quizzes, and scheduled messages; `q` is only briefly restated.

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 the specific resource and scope: folders of one template-library section, with `type` restricted to event, plan, or exercise. It also explicitly distinguishes Nolio built-in folders from usable owner folders and names a downstream sibling (`create_training_frame`) that consumes the folder id.

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

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

It gives concrete usage guidance: cite a folder `id` to file a template, only use `event` folders of `perso` or `team` with `create_training_frame`, never file templates in `nolio`, and pass `q` to search by name. It does not broadly compare against other list tools, but the operational when-to-use guidance is strong.

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 readOnlyHint and destructiveHint=false, the description discloses non-obvious behavior: Nolio metrics are included even when hidden from display, entries expose only definitions, computed metrics are never stored, and writing a value enrolls an athlete except for workout-aggregated metrics. These are substantive operational details rather than restatements of 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 content is dense and almost every sentence carries useful information, but it is presented as one long, run-on block with many nested clauses. It is not front-loaded into scannable guidance, making it harder to digest than necessary.

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

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

With no output schema, the description still explains the return shape (`id`, `key`, `unit`, `is_wb_compatible`) and routes the agent to the correct endpoint for values or computed data. It also covers unit suitability and enrollment constraints, so the tool is sufficiently explained for correct use.

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 already 100%, but the description adds workflow meaning: `athlete` selects another person's catalogue and drives the enrollment behavior, `is_wb_compatible` relates to %-metric targets, and `q` is recommended because catalogues run to hundreds. It does not restate syntax details, but it adds enough practical context 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 opens with a precise verb and resource: it lists the metrics available to a person, explicitly definitions only rather than values. It immediately distinguishes this tool from related value, computed, and records endpoints, so an agent can identify it without inspecting 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 gives explicit routing rules: values live on metrics/values/, computed metrics on metrics/computed/, and records on metrics/records/. It also explains when to pass `q` and how athlete enrollment affects missing metrics, 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 already cover read-only and non-destructive safety. The description goes well beyond them: newest-first ordering, page-until-`has_more`-is-false semantics, and the important caveat that values withheld by a device maker return empty with a `restriction` field and must not be treated as missing 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?

Front-loads the what, then a compact parameter block, then the caveat. Every sentence carries operational information; 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?

Output schema exists so return shape needn't be explained, and the description still covers the two things an agent would otherwise get wrong: how to paginate and how to interpret empty-with-restriction results. Nothing needed 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 0%, yet the description documents every parameter: `mti_…` handle format for metric, `usr_…` handle for athlete, 'YYYY-MM-DD' for the date window, `limit` capped at 100, and `starting_after` taking the last returned `id`. It fully compensates for the empty schema descriptions.

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 daily values of a metric') and enumerates example metrics (HRV, resting heart rate, sleep, weight, Hooper). It is clearly separable from the sibling list_metrics, which supplies the metric handles rather than the values.

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 tells the agent to omit `metric` for all metrics and omit `athlete` for its own values, and routes handle lookup to list_metrics. It gives clear context for each parameter but states no exclusions or when-not-to-use conditions versus other read siblings like get_records.

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 and openWorldHint=false, yet the description adds real value beyond them: sort order ('most recent first'), the meaning of `limit`, the status enum values, and the null-condition on `pdf_url` when Stripe has no PDF or is unreachable. It does not discuss pagination or how many rows exist by default beyond the schema's default.

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 scope statement and the when-to-use sentence before any field detail; each sentence serves a purpose. The row-field enumeration is somewhat long and partially duplicates the output schema, which keeps 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?

For a simple read-only list tool with annotations and an output schema, the description covers purpose, trigger, scoping exclusion, ordering, and return semantics. The only real gap is pagination/volume behavior, which an agent might want before requesting a large `limit`.

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

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

Schema description coverage is 0% and the single `limit` parameter is only glossed as 'max rows', with the default (10) left to the schema. That is enough for a one-param tool but does not compensate for the absence of schema descriptions.

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

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

States a specific verb and resource ('List your own Nolio invoices') and immediately scopes what an invoice is ('charges Nolio issued you for your platform subscription'), which separates it from athlete-facing siblings like list_athlete_subscriptions. An agent can select it 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?

Gives a concrete trigger ('when the user asks for their Nolio billing history, receipts or a downloadable invoice') and an explicit exclusion ('These are your invoices only, never an athlete's'). It stops short of naming a specific alternative tool (e.g. list_athlete_subscriptions or nolio_api_read), so it is clear but not fully 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 declare readOnly/non-destructive/closed-world, so the description is free to add what they can't: the result rows omit the workout itself, competitions are absent, and there is a has_more/pagination notion. It stops short of describing ordering behaviour or how far a window may span, so it isn't fully exhaustive.

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, exclusion and routing are front-loaded in that order, and every clause carries information. It is dense and slightly overloaded with cross-references (get_calendar, nolio_api_read, get_planned_training) 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?

There is no output schema, so the description's row-shape listing ({id, name, date_start, athletes, group, sport, has_structured_workout, …}) is genuinely load-bearing and it correctly warns the workout body is absent. The ellipsis leaves the full field set unknown, which is the only real 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 description coverage is 100%, so date_from/date_to, athlete, group, recurrence and limit are already documented. The description only adds guidance to keep the window narrow, which is a usage hint rather than parameter meaning — baseline 3 applies.

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

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

States a specific verb and resource (find planned training workouts on the calendar over a date window) and explicitly separates itself from competitions and from the get_calendar/read alternatives. An agent can tell exactly what this returns versus get_planned_training, which returns the workout body.

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 ('location step before reading or editing an existing workout'), explicit when-not ('this alone never answers what is on her calendar' because races are separate), and names concrete alternatives (get_calendar in planned mode, nolio_api_read on planned/competitions/). The follow-up step (read a candidate with get_planned_training) is spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and closed-world scope, so the safety bar is low. The description adds real value beyond that: permission-scoped visibility (only templates you can plan) and pagination semantics (`starting_after` = last returned `id`, paging continues while `has_more`). It doesn't mention rate limits or default page size, keeping it just short of 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?

Front-loaded with the core list scope, then a compact per-parameter block — no filler sentences. The phrasing of 'Pass one's qzf_… handle' is slightly awkward and the handle prefix requires inference, but the structure is otherwise tight.

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-value documentation is unnecessary; the description instead covers the only ambiguity that matters — how to page (`starting_after`/`has_more`) — plus scope and downstream use. For a zero-required-parameter read tool, an agent has everything needed 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 description coverage is 0%, so the description must carry all parameter meaning — and it does: `hooper_only` is defined by the metric it feeds, `limit` is capped at 100, and `starting_after` takes the last returned `id` with `has_more` as the continuation signal. Every one of the three parameters gains meaning not 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?

States a specific verb+resource (list questionnaire templates) and immediately bounds the scope: your own, your teams', and Nolio's Hooper questionnaire. It also distinguishes the tool's role from siblings by naming create_planned_event as the consumer of its output, which no other list_* sibling does.

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

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

Tells the agent exactly what to do with a result — pass the qzf_… handle as `quiz_template` to create_planned_event — and explains when to narrow with `hooper_only` (Hooper metric feeds). No competing tool lists quiz templates, so no exclusion clause is needed; the downstream routing is the guidance that matters.

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, non-destructive, closed-world), so the description's added value is the scope limits: only the caller's own deletions, a 30-day window, and most-recent-first ordering. That is genuinely useful disclosure, though the undo step is phrased loosely ('read it with `undo_deletion`') and never says what identifier to pass, which is the one operational detail an agent needs.

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 paragraphs, front-loaded with what the tool returns, then when to call it, then the constraint and the next step. Every sentence 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?

An output schema exists, so return values need not be explained, and the description covers scope, retention window, ordering, and the follow-up action. The remaining gap is the undocumented `limit` parameter and the missing identifier needed to hand an entry to `undo_deletion`.

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

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

There is a single parameter, `limit`, with 0% schema description coverage, and the description never mentions it, page size, or what happens when more entries exist than are returned. With one undocumented parameter the description should have compensated, 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?

States a specific verb (list), a specific resource (deletions made through this API), and a scope qualifier (still undoable). It is clearly distinct from the sibling `undo_deletion`, which acts on a single entry.

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

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

Explicitly names the triggering situations ('after a delete the user regrets', 'whenever they ask to undo, cancel or restore') and routes to the alternative tool `undo_deletion` with a precondition (the user has confirmed that exact entry). Nothing 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?

Beyond the read-only, non-destructive annotations, the description discloses default active-only filtering, how to retrieve hidden sports, the restricted use of the settings-row id, and the structured-workout flag requirement. These are substantive behavioral details an agent would not infer from 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 information-dense and front-loads the core purpose, with every clause serving a practical purpose. However, the long semicolon-heavy paragraph makes some details harder to scan than a more structured presentation would.

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 read-only list tool without an output schema, the description covers scope, defaults, id meanings, follow-up calls, and a key domain constraint for structured workouts. Nothing essential for correct invocation appears to be 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%, and the schema descriptions already explain both parameters thoroughly. The description adds useful context such as where the athlete id comes from, but most parameter meaning is already carried by the schema, so the baseline score is appropriate.

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

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

The description states a specific verb and resource: listing sports for a person, with default self-scope and optional athlete scope. It clearly distinguishes the tool from siblings like list_athletes and list_zones by explaining when each is relevant.

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

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

It gives explicit guidance on when to use the tool, how to obtain the athlete id, how to list hidden sports for reactivation, and when to call list_zones next. It also explains how to use returned sport ids in event planning.

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 safe read (readOnlyHint=true, destructiveHint=false, closed-world), and the description adds substantial context beyond them: results are pre-filtered to charts the athlete actually has data for, with concrete examples (a tag breakdown only appears when tags exist, zones_duration_<stream> only when a slice exists). It also enumerates the meaningful dimension and measure values, which is exactly the behavioral shape an agent needs.

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 one-line purpose, followed by structured detail on entry fields, filtering rules, and the athlete parameter. Slightly dense in the filtering sentence, 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 structure needn't be restated, and the description still explains the semantics of the returned fields (chart/dimension/measure) that the schema likely does not. Combined with annotation-covered safety and full parameter coverage, 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 description coverage is 0% for the single `athlete` parameter, but the description compensates fully: it specifies the expected 'usr_…' handle format for a managed athlete and that omitting it targets yourself. That closes the documentation gap the schema leaves entirely open.

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 and resource ('List the statistics breakdowns available for an athlete') and anchors it with the concrete page reference (/statistic charts). It immediately contrasts with the sibling that consumes its output (get_stats_chart), so an agent can distinguish the discovery step from the retrieval step.

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 states that each entry's `chart` id is meant to be passed to get_stats_chart, which establishes the two-step workflow and the alternative tool. It also explains the filtering condition (only charts the athlete has data for) and the self-vs-managed-athlete case, though it does not state outright 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful semantics beyond that: tags are author-owned, ids should be cited verbatim, and this channel cannot create tags.

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-load the core ownership constraint and stay on point; there is no filler. The phrasing is a bit repetitive about author vs athlete ownership, slightly blunting 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 single-optional-parameter, read-only tool with no output schema, the description covers the key ambiguity (whose tags) well. It does not indicate what the returned tag objects look like or whether there are pagination limits, 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 description coverage is 100% and the schema description for `athlete` already states 'their own tags, never to cite on a workout you author. Omit for yours.' The description largely restates this ownership rule, adding emphasis but not new format or syntax detail.

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 makes clear this retrieves tags ('tag_…') for labelling workouts the agent authors and that it is a read-only, existing-tags-only channel. The verb 'list' is only implied through the name/title, but the resource and scope are unmistakable and the creation-vs-read distinction is drawn.

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

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

It gives explicit guidance on the one branching decision: omit `athlete` for your own tags, and pass `athlete` only to read an athlete's own tags. It also excludes a wrong action outright ('no creation in this channel'), leaving little to 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds material context beyond them: a result cap with `has_more`, the exact entry shape returned, the ownership/assistant exclusion rule, and the meaning of `is_wb_enabled` as 'structured content is valid and watch-ready'. These are exactly the behaviors an agent needs and none are in 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 front-loaded paragraph: scope first, then return shape, then the paging/next-step guidance — nothing is buried. It is dense and jargon-heavy (tfr_…, spt_…, is_wb_enabled), but every clause carries actionable 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?

No output schema exists, and the description compensates by listing the exact entry fields returned, explaining the non-obvious `is_wb_enabled` and `family` values, and disclosing truncation behavior. Combined with the explicit handoff to get_training_frame for full content, an agent has everything needed to call and interpret this 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%, so the baseline is 3; the description adds practical guidance by naming `q`, `category` and `sport` as the refinement levers when results are truncated, and by tying `category`/`sport` usage into a workflow. It doesn't add syntax or format detail beyond the schema, so it stops short of 5.

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 ('Search the reusable training templates') plus a precise scope rule — own templates and team templates, excluding teams where the caller is only an assistant. This distinguishes it immediately from get_training_frame (full content) and apply_training_frame (applying), which are both named.

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?

Routes the agent clearly: cite `id` into apply_training_frame, fetch the workout tree via get_training_frame, and refine with `q`/`category`/`sport` when `has_more=true`. It never states an explicit exclusion (e.g. when to prefer list_library_categories for browsing folders instead), so it falls just short of a full when/when-not treatment.

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, non-destructive, and closed-world. The description goes well beyond them: zones are final resolved values ordered by rising intensity, grouped by stream, bounds are unit-converted, template_mode returns coach-scoped zone configurations with names, and zone targets remain portable and resolved per athlete server-side. This is rich behavioral context that an agent could not infer from 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 core purpose, then progressively adds filtering and template-mode details. Every sentence is relevant, though the single dense paragraph is longer than strictly necessary—the final sentence on portability, while useful, could be trimmed without losing critical 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 3-parameter tool with no output schema, the description covers the return format, ordering, grouping, unit conversion, template-mode behavior, coach/athlete scoping, and portability rules. Combined with annotations that cover safety, an agent has everything needed 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 100%, so the baseline is 3. The description adds meaningful constraints not present in the schema: `athlete` defaults to the caller's own zones, `template_mode` returns configurations rather than zones, requires `sport`, and must never be combined with `athlete`. These are important usage semantics that elevate it above the baseline.

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 ('list intensity zones'), defines the scope (one person, yours or an athlete's), describes the return shape (numbered zones with min/max bounds, converted to declared unit), and distinguishes it from siblings like list_sports and list_metrics. An agent can immediately tell what this tool does and what it returns.

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 explicitly prescribes when to use each mode: a bare call returns all zones grouped by stream, `sport` filters to one sport using a list_sports entry, and `template_mode=true` is reserved ONLY for authoring a reusable training_frame (coach-scoped, sport required, never combined with `athlete`). It also points to list_metrics for %-metric targets. No ambiguity remains.

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 readOnlyHint annotation by disclosing pagination mechanics (collection responses carry {data, has_more}, next page via starting_after with the last returned id, same filters), default page size 10 and max 100. It also states what is never returned (GPS and location curves) and how the fields param trims payloads, which is exactly the operational detail annotations cannot convey.

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 and usage rule, then layered detail on path, params, pagination, fields and exclusions. It is dense but nearly every sentence carries operational information; the example lists are slightly long but they substitute for the missing schema descriptions.

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, yet the description still notes the envelope shape ({data, has_more}) because callers must act on it for pagination. Combined with the path format, param examples, page-size limits and excluded data categories, an agent has everything needed to call a generic open-ended endpoint 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 0%, so the description carries the full burden and does so convincingly: `path` must be a v2 path without the /api/v2 prefix, with four concrete examples, and `params` are query params illustrated with date_from/date_to/limit plus the cursor and fields cases. This turns two undocumented free-form parameters into something an agent can use correctly on the first try.

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 any Nolio API v2 GET endpoint.' It immediately delimits scope ('GET endpoint', 'no curated read tool fits'), which cleanly separates it from nolio_api_write and the curated read tools like get_records or get_calendar.

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 selection rule: use this when no curated read tool fits. That is genuine routing guidance rather than inference. However, it does not name the closely related helpers get_endpoint_schema or search_nolio_api_docs, which an agent would need to discover the correct path — the natural next-step alternatives go unmentioned.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes beyond that with a concrete safety protocol for batch writes: dry run, show the person the recap, wait for explicit 'yes' even if the request sounded explicit. That is real added behavior. It falls short of 5 because it says nothing about auth/scope requirements, error behavior, or whether a committed destructive call can be undone (relevant given undo_deletion/list_recent_deletions exist).

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

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

Front-loaded with purpose and scope in the first two clauses, then parameter mechanics, then the safety protocol. Inline examples replace prose description, and the batch-commit rule is compressed into one dense but readable sentence. No filler.

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

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

Output schema exists, so return values need no explanation, and the description stays focused on what the schema cannot convey: path formatting, body shape sourcing, and the confirmation workflow. For a generic destructive escape-hatch tool with 0% schema documentation, this is as complete as the description needs to be.

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 all three parameters, and it largely does: `path` gets the critical format rule (no /api/v2 prefix) plus concrete examples across POST and DELETE, and `body` is explained as the JSON payload with a pointer to get_endpoint_schema for the exact shape. It never states that `method` must be one of the four listed verbs or gives its casing/format explicitly, which is the remaining gap.

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

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

States a specific action and resource ('Write to any Nolio API v2 endpoint') and enumerates the methods in scope (POST/PATCH/PUT/DELETE). The follow-up clause 'Use when no curated tool fits' separates it cleanly from the ~30 curated write siblings (create_planned_event, update_training_frame, delete_event, etc.).

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 routing rule: use only when no curated tool fits, which is exactly the discriminator an agent needs against the large sibling set. It also names a required prerequisite step ('check the exact shape with get_endpoint_schema first') and prescribes the multi-call commit flow, so the agent knows both when to select this tool and what sequence to run.

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/non-destructive/openWorld=false, and the description goes well beyond them: per-mode sort order (oldest first for event, newest first for thread and list), the 100-message cap per conversation, the meaning of `has_more`, and how to backfill older messages. This is exactly the behavioral context annotations cannot express.

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 one-line purpose, then a bulleted mode list with the shared paging rule last. Dense but every clause carries information an agent needs; nothing is 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?

For a 5-param, zero-required, output-schema-backed read tool, the description covers mode selection, ordering, paging, and truncation behavior. Return shape is intentionally left to the output schema, which is the right division of labor.

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

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

Schema description coverage is 0%, and the description does give meaning to all five parameters (event as workout/trn_/ptrn_ handle, thread as conversation handle, limit with max 100, starting_after as last returned id, unread_only for filtering). However, it omits the default `limit` of 20 and doesn't restate types or that all params are optional, so the schema still carries some weight the prose 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 specific verb and resource ('Read the messages between a coach and athletes') and immediately enumerates the three concrete modes (event, thread, neither), so an agent knows exactly what each invocation returns. No sibling tool in the list covers conversations, and the description makes the boundary obvious.

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 says 'three uses, one at a time' and gives the selecting condition for each mode, including where the `ptrn_…` handle should come from (get_calendar). It also routes the agent to `thread` + `starting_after` when `has_more` is set, which is genuine when-to-use 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?

Beyond the destructiveHint/readOnlyHint annotations, the description discloses that the athlete is notified of the message and that a sent comment cannot be taken back from this tool. That is exactly the irreversible side-effect context an agent needs before calling a destructive tool.

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

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

Front-loaded with the coach-only scope and the core action, then a per-parameter block. No sentence is redundant; the caution about approval and irreversibility is placed where it matters.

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 2-parameter destructive mutation with an output schema and full annotations, nothing essential is missing: permissions, id provenance, comment restrictions, notification, and irreversibility are all covered.

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

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

With 0% schema description coverage, the description fully compensates: `id` is defined as a trn_… workout or cmp_… race handle from get_calendar(mode='real'), and `comment` is defined as a message the athlete is notified of, valid on workouts only. Both parameters gain meaning not present in the bare 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: marking a managed athlete's completed workout or race as viewed, and optionally posting a comment. It also names the sibling tool that produces the required id (get_calendar) and scopes the tool to coaches, so an agent can distinguish it from read-only siblings immediately.

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 preconditions are given: coach-only, id must come from get_calendar(mode='real'), comments are valid on workouts only, and the coach's go-ahead must be obtained before posting. These are concrete when/when-not rules rather than implied usage.

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 read-only annotations, the description discloses important behavior: curated and raw results are ranked together, curated results carry defaults and guardrails, raw paths must be resolved via get_endpoint_schema, and raw routes already covered by curated tools are suppressed. This materially helps an agent interpret results and avoid misusing raw endpoints.

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 then explains result handling efficiently. Every sentence adds operational value, with no redundant restatement of the tool name or schema.

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

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

Given that an output schema exists, the description need not enumerate return fields. It supplies enough context about result categories, routing decisions, and query semantics for an agent to invoke and use the tool 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 0%, so the description carries the burden for the single query parameter. It adds useful semantics by saying the query may be one or several keywords and gives examples like 'records', 'hrv metric', and 'plan a workout', though it does not specify exact keyword separator or matching rules.

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: find/rank curated tools and raw OpenAPI endpoints for keywords. It clearly distinguishes this discovery tool from sibling action tools by explaining that curated results name callable tools while raw results are API paths for nolio_api_read/nolio_api_write.

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 using the tool to find the best tool for a task and explains what to do with both result types: call curated tools directly, or use a raw path with the generic API tools and get_endpoint_schema. It names relevant alternatives but does not explicitly state when not to use this search 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?

Beyond the annotations, it discloses the dry-run preview behavior, the cascading scope of deletions, the `impact` and `blocked_reason` response fields, and the required user-confirmation sequence. This is substantial behavioral context for a mutation/restore tool.

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

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

The description is front-loaded with purpose and parameter meaning, then adds operational safeguards. Every sentence carries useful information about previewing, cascading effects, confirmation, or safety constraints.

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

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

Although an output schema exists, the description still helpfully references key response fields (`impact`, `blocked_reason`) and fully explains the required call sequence. For a restore operation with cascading effects, the description provides everything needed to invoke it safely.

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 fully compensates: `id` is a `rcv_…` handle from `list_recent_deletions`, and `confirm` controls whether the operation previews or executes. Both parameters gain meaning beyond their schema types.

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 precise verb and resource: "Restore data deleted earlier." It distinguishes this tool from the related listing tool by specifying that `id` comes from `list_recent_deletions`.

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 two-step workflow: first call without `confirm` to preview impact, then call with `confirm=true` after user approval. It also names clear exclusions: never infer the target and never undo entries with a non-empty `blocked_reason`.

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 readOnlyHint=false; the description goes well beyond that by explaining irreversibility, requiring user confirmation, disclosing the ownership restriction, clarifying that is_visible=false only collapses (the folder stays listed), and warning that in-app deletion also destroys every template inside.

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?

Capabilities are front-loaded in the first sentence, the safety warning follows, and per-parameter notes are compact and scannable. Every clause adds decision-relevant information; nothing is restated from annotations or schema.

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

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

Output schema exists so return values need no explanation, and the description still covers safety, ownership limits, parameter meaning, and the out-of-scope delete path. An agent has everything needed to decide whether to call it and how to fill the payload.

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%, so the description carries the full burden and does: id is a cat_… handle from list_library_categories, parent must be a root folder handle of the same owner and type, is_visible=false means collapse-but-stay-listed, and name maps to the rename operation. The parent constraint (same owner and type) is genuine meaning added beyond the string type.

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

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

Opens with the three concrete operations it performs on a specific resource: rename, re-parent, or collapse a library folder. It also rules out the delete case by naming where deletion lives, so an agent can distinguish it from create_library_category, list_library_categories, and any delete path without reading a sibling 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 preconditions and prohibitions: changes are irreversible so the agent must state the change and get approval first, Nolio's own folders cannot be modified, and deletion must happen in the app. It even names list_library_categories as the source of the required id handle.

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?

It corroborates and enriches destructiveHint=true: changes are irreversible, so confirm with the user first, and only the fields you pass change (partial update semantics that annotations do not convey). It also discloses refusal behavior—non-permitted fields rejected, overlapping cycles rejected, plain-text description rejected once HTML exists—which is exactly the kind of consequence context a mutating tool needs.

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 destructive warning and the id/ownership lookup, then neatly grouped per event type so an agent can read only the relevant block. It is long, but 23 parameters at 0% schema coverage justify it; the creation-oriented quiz/question and date_end details are the main material that does not earn its place in an update 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?

With an output schema present, return values need no explanation, and annotations plus description together cover safety, refusals, and field semantics thoroughly. The one substantive gap is the mismatch with the actual schema: the agent is told to send quiz_template/questions or creation-required date_end, which this schema does not accept, so a caller could plan a call that fails.

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%, so the description must do all the work, and it largely does: id prefixes, athlete vs group vs neither ownership, per-type field lists with formats (HH:MM, YYYY-MM-DD), value sets (goal_type 'a'/'b', note_type, question types), and validation rules. The deduction is for mixing creation-only requirements into an update tool—`date_end` "required on creation", and `quiz_template`/`questions`, which are not in the schema at all and would be rejected by additionalProperties:false.

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 first sentence states a specific verb ("Change") and the four resource kinds, each named in the title as well (race, cycle, note, questionnaire). It is clearly separable from siblings create_planned_event, delete_event, and update_planned_training 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?

It states required preconditions (read the event with get_calendar(mode='planned') to obtain the pcmp_/pcyc_/pnot_/pqz_ handle; use list_sports, list_quiz_templates, list_metrics for IDs), gives the exact workflow for description edits, and names hard exclusions: questionnaire questions cannot be changed, an answered questionnaire cannot be changed at all, and other fields are refused.

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 readOnlyHint=false, and the description goes well beyond them: it discloses that the workout array is full-replace, that nodes kept from the read must carry their "id" and the server then preserves web-editor state, that a node without id is created new, and that the audience is only patchable under recurrence_action=one. These are the exact semantics an agent would otherwise get wrong on a destructive mutation.

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 dense sentences with the workflow front-loaded before the constraints, and no filler. The parenthetical asides are long, but each carries a distinct rule (id preservation, comment fallback, confirmation threshold) rather than repeating 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 destructive, deeply nested mutation with no output schema, the description covers the workflow, identity preservation, the comment escape hatch, and the confirmation gate — enough to call it safely. It stops short of describing failure modes (revision mismatch, validation rejection) that the schema documents but a quick-scanning agent might miss.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in depth, and the description's audience/recurrence_action sentence largely restates the patch schema text. The node-id preservation guidance is genuinely useful but also echoed in the schema's id fields, so this dimension lands at the baseline rather than above 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?

The opening sentence states a specific verb and resource ("Update a planned training workout") and immediately establishes the read-modify-write pattern. It does not explicitly differentiate itself from near-name siblings such as update_planned_event or create_planned_training, so an agent must infer the boundary from the resource noun 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?

Explicitly names the prerequisite tool ("Read it first with get_planned_training"), the intermediate step ("apply your changes in reasoning"), and the fallback for unrepresentable intent ("put it in the comment of the relevant node — never approximate it"). It also defines a concrete escalation rule: more than 3 write operations requires listing computed dates/targets and getting explicit confirmation.

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 readOnlyHint=false, and the description correctly reinforces that instead of contradicting it, adding that kept nodes retain their id and that the server preserves web-editor settings on them. The id-omission-equals-new-node rule is real behavioral disclosure the annotations cannot carry. It stops short of stating what happens to nodes dropped from the re-emitted array.

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 sentences, purpose front-loaded, then workflow, then the id rule, then two guardrails. Every sentence carries either a procedure or a constraint, and nothing repeats the schema verbatim.

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 a very deep nested schema and no output schema, the description covers the parts that matter operationally: read-first, id preservation, the comment escape hatch for intent the schema cannot express, and a confirmation gate for large writes. Required category, revision token and full-replace semantics of `workout` are all carried by the schema.

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

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

Schema description coverage is 100%, so all three parameters and the deep nested node types are already documented in the schema — baseline 3 applies. The description adds one genuinely useful overlay (id preservation vs. new-node creation, which the schema also repeats per node type) but no additional semantics beyond that.

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

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

States a specific verb and resource — "Update a library workout template" — which separates it from create_training_frame and list_training_frames. It also names get_training_frame as the mandated read step, but never distinguishes itself from apply_training_frame or update_planned_training, so an agent must infer which update path applies.

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

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

Gives an explicit read-modify-write sequence: read with get_training_frame, compute changes in reasoning, then send the patch. Also adds a threshold rule (more than 3 write operations requires listing computed dates/targets and getting confirmation). No stated when-not or alternative-tool routing.

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