Povver — Strength Training

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

Annotations already declare a safe read-only, closed-world operation, so the bar is lower. The description still adds real behavior: cursor pagination semantics for 'sets' ('next_cursor; keep every other argument the same'), the partial-week caveat, and that fuzzy name matching requires checking meta.resolution in the answer.

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 single governing rule ('pick the view by the question') before the view catalogue. The dense ·-separated list packs nine view semantics, their parameters, and three caveats into a few lines with no filler sentences.

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, read-only tool with no output schema, the description covers the required view enum, per-view parameter applicability, pagination, and even partial return hints (PRs, bests, next workout, resolution). What it omits — full return shapes and limits on 'sets' paging beyond the cursor — is minor given the annotation coverage.

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 82%, so a baseline of 3 applies. The description goes beyond it by mapping parameters to views (muscle_group for muscle_state/muscle_group_progress, weeks for progress/status, exercise_name/exercise_ids for exercise_progress, include_all for recommendations) and clarifying 'omit for all', which the schema does not state as a cross-parameter rule.

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 ('Training analysis') and immediately clarifies the core mechanic: the view parameter selects the analysis. The nine enumerated views make the scope unambiguous. It does not explicitly distinguish itself from siblings like read_workouts or exercises, which keeps it from a 5.

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

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

Each view is paired with the question it answers ('strength_climb: am I getting stronger', 'insights: weekly review', 'status (weeks): adherence, next workout'), which is an effective routing guide. It also flags the partial_week caveat for week-to-date data. It stops short of naming when to prefer a sibling tool instead.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description layers on genuinely new context: the action is irreversible ("cannot be undone"), requires explicit user consent, and has differing cascade effects per kind. That cascade detail – routine templates survive, template is detached from every routine – is not derivable from any structured field.

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

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

One dense front-loaded sentence leading with permanence and irreversibility, followed by compact per-kind and per-param fragments. Very efficient, though the trailing "id: the item's id" fragment is pure redundancy against the schema.

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

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

For a destructive, no-output-schema tool this covers the essentials: irreversibility, consent gating, and per-kind consequences. The only omission is any hint about what a successful versus failed deletion returns, which is minor since the outcome is essentially binary.

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

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

Schema coverage is 67%, and the description compensates well for the enum parameter by explaining the side effects of each kind value rather than just restating them. It also clarifies that confirmed must follow user agreement. The id gloss ("the item's id") merely repeats the schema, which holds it back from a 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?

"Permanently delete one item" gives a specific verb and resource, and the per-kind clause spells out exactly what gets removed for workout, routine, and template. No sibling tool performs deletion, so the agent can identify this tool instantly and knows the exact scope of each call.

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 a concrete precondition – confirmed:true only after the user agrees – which is exactly the gating behavior an agent must respect for a destructive call. There are no competing delete tools to route against, so the absence of explicit alternatives is not a gap, but no when-not guidance is offered either.

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/openWorld=false/destructive=false, so the safety profile is covered. The description goes further by disclosing ranking behavior (by the muscles a lift trains), locale-aware translated names, and the limit ceiling of 100, which are behavioral traits 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?

One dense sentence front-loads the resource, then structures the two views as labelled segments, ending with the cross-tool pointer. Every clause carries information, though the single-sentence packing makes it slightly harder to scan than a two-line breakdown would be.

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

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

There is no output schema, so the description must carry return semantics – and it does, naming muscles, equipment, measures and instructions for detail and ranked, locale-aware names for search. What it omits (pagination or result-shape detail for search beyond the limit) is minor for a read-only catalog 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 already 80%, but the description adds real semantics: query accepts natural language, muscle groups or movements, and locale defaults to the user's language with translated names returned. It also scopes exercise_id to the detail view and to its later use in save_plan/log_workout/live_workout, which the schema's terse 'detail: the exercise.' does not convey.

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

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

States a specific resource (the exercise catalog plus the user's own exercises) and enumerates the two distinct operations under view, making clear what search versus detail each return. The closing sentence ties the tool to its siblings (save_plan, log_workout, live_workout), so an agent can place it in the workflow 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?

Explains when to pick each view – search for querying by words, muscle group or movement, detail for one exercise's full attributes – and names the downstream tools that consume the result. No explicit when-not-to-use or alternative tool is given, but the conditional routing between the two views is unambiguous.

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/openWorldHint/destructiveHint, so safety is covered; the description goes further by disclosing per-view payload contents and flagging that include_data_quality costs 'one more scan' — a real performance hint. It omits auth/permission requirements and whether the last-10-sessions block is windowed or capped.

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 'Call this FIRST' directive are front-loaded, then the view legend follows in a scannable dot-separated list. It is dense and slightly telegraphic, but every clause carries information and nothing is padded.

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

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

With no output schema, the description carries the return-value burden and does so view by view, plus a default and a cross-reference to povver://guide/tools. Two optional params, a read-only tool, and no missing call-critical information.

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

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

Schema coverage is only 50% (the enum values for 'view' carry no descriptions), and the description fully compensates by defining all three views' contents and stating that include_data_quality adds the data_quality block / e1RM coverage. This is meaning an agent could not derive from the schema alone.

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 the resource precisely ('who the user is and where their training stands') and enumerates exactly what each view returns, so an agent can picture the payload before calling. It does not explicitly differentiate itself from overlapping siblings such as read_workouts or analyze_training, which keeps it short of a 5.

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

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

'Call this FIRST' is an unambiguous sequencing instruction, making the intended entry point clear. However, no when-not conditions or named alternatives are given (e.g., when to prefer profile over snapshot, or when read_workouts supersedes it), so the routing guidance is directive but incomplete.

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

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

Annotations already declare destructive=true and idempotent=true, but the description adds non-obvious behavior: actions execute in order and are NOT atomic, the first refusal stops the rest, 'start' never replaces an existing session, and request_id reuse is only for retries. That is exactly the kind of partial-failure and retry semantics an agent needs before calling a mutating 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 core purpose, then the invocation rules, then the action catalogue — a sensible ordering with almost no filler. The action list is long but each entry carries distinguishing semantics rather than restating the enum 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 multi-action mutation tool with no output schema and 20+ nested action properties, the description covers sequencing, failure, versioning and start semantics well. It stops short of describing error/refusal response shape or how to resume after a mid-batch refusal, which would complete the picture.

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

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

Schema coverage is only 33%, but the description compensates: it explains request_id lifecycle, ties expected_version to read_live_workout's state_version, and disambiguates action types the bare enum cannot (log_set_shorthand = next planned set, start alone or template_id vs next routine workout). Many nested per-action fields (set_id, position, measure, reason) still rely on 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 ('Start a workout or act on the one in progress') and enumerates the 15 action types, so an agent can distinguish it from read_live_workout (read) and log_workout. The scope is unambiguous.

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

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

Gives concrete operational rules: send a NEW request_id each turn (same one only to retry), pass state_version from read_live_workout as expected_version, and 'start' must be alone in its call. It does not explicitly say when to prefer this over the sibling log_workout, which is the one remaining gap.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description explains the mechanisms behind both: 'exercises REPLACES the list' (what gets destroyed) and 'client_ref makes a retry safe' (why retries are safe). It also discloses the error path — an unknown exercise_id returns candidates — which is valuable recovery behavior.

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

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

Highly compressed and front-loaded: scope first, then create, then update, then the live_workout alternative, then a guide pointer. The dense bullet style is efficient, though a few fragments (e.g. the bare guide URI) are terse enough to slow comprehension.

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

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

For a 3-param, deeply nested mutation with no output schema, the description covers action branching, idempotency keys, replacement semantics and an error path, deferring import details to a guide. It stops short of describing the success response or how supersets interact with deletion, which is a minor gap rather than a blocking one.

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

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

With only 33% schema description coverage, the description carries real weight: it documents create bounds (1-25 workouts, client_ref, end_time, exercises and sets), is_final on the last chunk, and update semantics (workout_id plus only changed fields). It does not explain supersets, import_id chunking consistency, or the positional/measure fields, so it is strong but not complete.

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 pair and resource plus the scope restriction: 'Record or correct FINISHED workouts'. The word FINISHED immediately separates it from the in-progress sibling, and it then names live_workout explicitly for that case.

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

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

Gives explicit routing: create vs update, when to use live_workout instead, and the prerequisite step 'read_workouts(detail) first and echo each set id'. It also points to exercises(search) for exercise_id and to an external guide for import rules.

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 this as a non-read-only, destructive tool, so the burden is lighter. The description nonetheless adds high-value behavioral context the annotations cannot: accepting a recommendation mutates the template immediately and must be gated behind user agreement via confirmed:true, which is the key safety nuance for this 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 purpose sentence followed by a compact, scannable action/parameter breakdown with no filler. The parenthetical enumerations lean on schema data, but they earn their place by binding parameters to their action.

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 three-mode tool with no output schema, the description covers every action, its inputs, and the one dangerous path (accept + confirmed). What each action returns and validation constraints (lengths, maxItems) are left to the schema, which is acceptable, but return behavior for a destructive mutation is a remaining gap.

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

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

With 12 parameters at 67% schema coverage, the description's action-to-parameter mapping (which fields belong to save_injury vs set_status vs review_recommendation) is genuinely additive because JSON Schema cannot express conditional per-action requirements. It does not mention idempotency_key, so the coverage is good but not complete.

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 verb+resource (change injury memories, answer recommendations) and the three named actions (save_injury, set_status, review_recommendation) make the scope concrete. It implicitly contrasts with the read_memory sibling by being the mutation counterpart, but never names that sibling, so the differentiation is inferable rather than explicit.

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

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

Each action is paired with the parameters it expects, and review_recommendation carries a real precondition (accept changes the template at once and needs confirmed:true after the user agrees). There is no explicit when-not-to-use guidance or routing to read_memory/delete for the non-mutating cases, so it falls 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety posture is partly covered. The description adds real behavioral context beyond that: the confirmation gate for editing active plans, and the state semantics of pause ('the policy is kept') vs resume ('re-activate'), plus the dry-run recommendation. It stops short of describing irreversibility or what happens to in-flight routines.

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 core purpose in one clause, then uses compact separator-delimited action breakdowns. Dense but every element earns its place; the parenthetical caveats are tightly scoped. Slightly cluttered by nested parentheses but no wasted sentences.

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 nested plan object, no output schema and an undefined return, the description covers action semantics, scope boundaries, confirmation requirements and the preview workflow. Given the schema already supplies field shapes and the linked periodization guide, the remaining gap (no mention of response/confirmation feedback) is minor.

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

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

Schema coverage is 67% and the description meaningfully supplements it, explaining what 'plan' is (a policy with phases, step ceiling, deloads) and its boundaries, what each action value means, and the conditional role of 'confirmed'. This adds semantics beyond the enum and nested 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 ('Change the periodization plan') and then enumerates the three concrete mutations (set/pause/resume) with what each does. It explicitly distinguishes its scope from the sibling save_plan ('it CANNOT define exercises or sets, use save_plan for those'), so an agent can tell the two apart without opening either schema.

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

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

Each action carries its own when-to-use condition: set for authoring a steering policy, pause to return to the automatic engine, resume to re-activate. It names the alternative for a related need (save_plan) and the prerequisite workflow (edit an active authored plan needs confirmed:true after user agreement; dry-run first with read_periodization(preview)).

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' readOnly/no-destructive profile, it discloses the empty-state response contract (active:false, no_active_workout) and, importantly, the concurrency semantics of state_version (pass it as live_workout expected_version). That is exactly the behavioral context an agent cannot get from the structured fields, especially with no output schema.

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

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

Three dense sentences, each load-bearing: return contents first, then the version-passing instruction, then empty-state and routing. No filler, no restatement of the title.

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

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

With no output schema and no parameters, the description carries the full disclosure burden and does it: it sketches the return payload, the failure/no-session shape, and the cross-tool workflow. 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?

The tool takes zero parameters (empty properties object), so per the baseline there is nothing for the description to disambiguate at the input layer. Score is held at 4 rather than 5 because the description's state_version note is about a sibling's parameter, not this tool's own inputs.

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

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

States a specific verb+resource ('The workout in progress right now') and enumerates what it returns: every exercise and set with ids, the next set, totals, and state_version. It explicitly distinguishes itself from read_workouts ('Finished sessions: read_workouts'), so an agent can pick the right tool without opening any schema.

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

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

Gives explicit routing: use live_workout with action start to begin a session, this tool when a session is running, and read_workouts for finished sessions. It also names the no-session case ('Answers active:false with no_active_workout when no session is running'), covering when-not conditions as well as alternatives.

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 openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely useful behavior context — that the default list view returns active and monitoring memories and that these 'gate training', plus default limits (50 for list, 10 for suppressions) — but says nothing about permissions, ordering, or pagination. Solid but not rich.

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

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

One dense paragraph with the core purpose front-loaded and per-view details grouped behind middot separators; nearly every clause carries information. The packing is heavy for a single sentence chain, which slightly hurts skimmability, but there is little waste.

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

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

For a 5-parameter read tool with no output schema, the description usefully describes what each view surfaces (category, status, status history, severity, body_area, held-back progressions), covering the return shape that the schema omits. Remaining gaps — default sort order and whether list is paginated — are minor for a read-only tool.

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

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

Schema description coverage is only 40%, so the description has to compensate, and it does: it maps category and status to the list view, ties memory_id to detail, and documents limit ceilings per view (200 for list, 50 for suppressions). It doesn't explain, e.g., what status values mean semantically, 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?

States a specific verb+resource ('read' what the user asked Povver to remember) and enumerates the three views with their scopes, so an agent can tell exactly what each mode returns. It also explicitly distinguishes itself from the mutation sibling ('Change them with manage_memory'), making it easy to route between read_memory and manage_memory.

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?

Each view's purpose is spelled out (list = default active/monitoring memories that gate training; detail = per-memory history/severity; suppressions = progressions held back by an injury memory), which effectively tells the agent when to pick each. The read-vs-change boundary is stated via manage_memory, but there is no explicit when-not guidance beyond that.

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, lowering the burden. The description still adds value by clarifying that preview 'validates a policy and shows what it would do; writes nothing,' and by listing what current returns (phases, policy, status, next_session). It stops short of describing error or empty-state behavior.

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

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

Highly front-loaded and dense, using separators to pack view semantics, the resource pointer, and the mutation sibling into a few lines with no filler. The telegraphic fragments are efficient, if slightly terse, but every element earns its place.

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

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

For a two-parameter read tool with no output schema, the description covers the views, what current returns, the non-mutating nature of preview, a resource pointer for plan shape/rules, and the change path via manage_periodization. Adequate, though the nested plan object's expected shape is delegated entirely to the external resource.

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

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

With 50% schema coverage, the description compensates: the 'view' enum values are fully explained in prose, and it links the 'plan' object to the preview view and to manage_periodization(set). This adds meaning beyond the bare enum and the schema's single plan description.

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

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

The description states the resource ('the periodization plan') and enumerates the two views with their contents, so an agent knows this reads the plan in one of two modes. It names the sibling that mutates it (manage_periodization), aiding differentiation, though the read verb itself is carried mainly by the name rather than the prose.

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

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

It clearly distinguishes when to use each view: 'current' for the existing auto-generated or authored plan, 'preview' for validating a policy without writing. It also routes write operations to manage_periodization. No explicit 'when not to use' statement, but the view conditions and the sibling hand-off are actionable.

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 openWorldHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: what each view actually returns (all routines plus the active one, template metadata vs 'the full prescription with element ids, coach_note, superset groups and version'), which is valuable since there is no output schema.

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

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

A single dense paragraph using '·' separators, front-loaded with the scope and then per-view detail; essentially every clause carries information. The packing makes it slightly harder to scan than separate sentences would, but nothing is wasted.

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

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

For an 8-parameter, five-mode tool with no output schema, the description covers the essential decision inputs: mode selection, required ids per mode, and the shape of each return. Minor gaps remain (defaults, id stability, pagination/limits), but nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is only 38% (equipment, split_type, fitness_level and include_templates carry no schema description), but the description compensates by naming exactly which parameters drive each view — split_type/frequency/equipment/fitness_level for seed_templates, routine_id for routine, template_id for template, include_templates=false for metadata-only. It does not explain enum value meanings or the boolean default, so this is strong but not exhaustive.

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

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

States a specific verb+resource (read routines and workout templates) and immediately distinguishes itself from the mutation sibling by naming save_plan as the tool for changes. An agent can tell what this tool returns and what it is not for 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?

Each view is enumerated with its purpose, which effectively tells the agent which mode to pick for which need, and 'Change them with save_plan' explicitly routes write intent to the alternative. It stops short of task-level triggers or exclusions (e.g. relation to read_workouts / live_workout state), so it is clear context rather than a complete when/when-not matrix.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: notes and gym names are athlete-authored text to be treated as data and never instructions (a prompt-injection caveat), plus pagination and result-cap behavior. Return format is sketched but not exhaustively.

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 core purpose ('Read FINISHED workouts') then branches per view using a compact sectioned notation. Every clause carries information — result counts, pagination, injection safety, the sibling pointer — with no filler. The telegraphic '·' style is dense but readable.

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

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

There is no output schema, so the description must convey return shape, and it does: list returns summaries with working_set_count, total_set_count_including_warmups, notes, and gym; detail returns set-level data with set IDs and optional per-muscle analytics. That is sufficient for correct invocation, though error cases and cursor expiry behavior are unaddressed.

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

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

Schema description coverage is only 60% (view and verbosity have no schema descriptions), so the description must compensate — and it does, explaining what each enum value yields and what 'full' adds (per-muscle analytics). It also clarifies cursor as 'next_cursor from the previous page' and the limit cap, which the schema states only tersely.

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 plus its scope: 'Read FINISHED workouts.' It explicitly carves out the boundary against the sibling that could be confused with it ('The session in progress: read_live_workout'). An agent can distinguish read_workouts from read_live_workout without opening either schema.

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

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

Routes clearly between the two modes: list for paginated summaries, detail for set-level data tied to a workout_id, and it names the alternative (read_live_workout) for in-progress sessions. It also gives a concrete trigger for detail ('which log_workout update needs echoed'). No explicit exclusions or prerequisites beyond that, so not a 5.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description spells out exactly what is destroyed or preserved: template_ids replaces the list, exercises REPLACES the list, and coach_note is cleared when omitted. It also discloses STALE_STATE on expected_version mismatch, idempotent resend behavior for client_ref, and that weights are snapped to the user's load grid.

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 purpose before any detail, and the action list is compressed into a single dense clause per action. The length is justified by the 15-parameter mutation surface, though the run-on action list is harder to scan than separate lines 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?

For a destructive multi-action mutation tool with no output schema, the description covers the essential behavioral contract (what replaces what, version echoes, idempotency) and notes the return is the saved object. It omits permission/auth requirements and recovery steps after STALE_STATE, which would round it out.

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 67% schema coverage, the schema already documents many fields, but the description adds cross-parameter meaning the schema cannot: which fields belong to each action, ordering semantics for template_ids, the slot meaning of start_index, and the version echo requirement. Secondary params like avoid, requested, and pairing_requested_by_user remain only schema-documented.

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 pair and resource ('Create or change routines and templates') and then enumerates all five actions with their field signatures. An agent can distinguish this mutation tool from read_plans without opening the schema, since the read path is only named as an input dependency.

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

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

The per-action breakdown effectively routes the agent to the right operation, and it names read_plans as the required source for echoing element ids. It stops short of explicit when-not guidance (e.g. preferring read_plans for inspection, or confirming with the user before destructive replacement), so it is clear context without exclusions.

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

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

Beyond the annotations (which only declare non-read-only, non-destructive, closed-world), the description discloses a concrete rate limit (at most 10 per hour), idempotency semantics via client_ref (same key returns the first result and sends nothing new), and consent/privacy constraints on message content. These are real behavioral traits an agent cannot get from structured fields.

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

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

Front-loaded with purpose, then usage triggers, then parameter guidance in a compact telegraphic style; every clause carries instruction. The dense parameter run-on reads as a spec dump, but nothing is wasted.

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

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

There is no output schema, and the description still covers the relevant return behavior in idempotency terms (same client_ref returns the first result), plus limits, privacy rules, and consent workflow. Nothing an agent needs to invoke this six-parameter write tool 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 already 83%, so the baseline is 3; the description reinforces the key parameters with operational framing (type enum values, the 4000-char message bound, client_ref as a safe-retry key, contact_email only for replies, prompted_by only when a Povver note asked). Much of this restates schema descriptions, but the retry-safety and consent framing adds usable meaning.

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 (send) and resource (bug report, feature request, feedback) addressed to a named recipient (the Povver team). No sibling tool overlaps with this capability, so an agent can select it without ambiguity.

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 covers both triggers: when the user asks, and proactive offering after an unexpected tool error, a missing capability, a confusing or wrong result, or a workaround. It also states the preconditions for sending (show the exact text first, never include other people's data), leaving nothing 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 the safety profile (readOnly, non-destructive, not open-world), so the bar is lower. The description adds genuinely useful behavior beyond that: the structure of both sections, that roadmap items lack dates and 'may change', and the status values (planned or in_review) – important volatility context for how much to trust roadmap output.

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 tool's purpose, then the two result sections, then usage. Every sentence is informative, aside from the slight redundancy of repeating the limit definition already given in the schema.

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

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

There is no output schema, so the description carries the burden of explaining return values – and it does, detailing both shipped (date, headline, release notes) and roadmap (title, bullets, status) shapes. Nothing an agent needs to interpret or call this tool 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?

There is only one parameter and schema description coverage is 100%, so the baseline is 3. The description restates 'limit: how many shipped versions (1-20, default 5)' essentially verbatim from the schema, adding no meaning beyond it.

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

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

States a specific resource (what Povver has shipped and what is planned) and anchors it to a concrete source (same text as povver.ai/updates). It also breaks the return into two clearly named sections, shipped and roadmap, so an agent knows exactly what this covers. None of the siblings (workouts, plans, memory) overlap with app release/roadmap data.

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 trigger phrases ('what's new', 'is X out yet', 'is X planned') plus a negative directive ('do not guess'), which is strong routing guidance. It does not name an alternative sibling to use instead, but no sibling plausibly competes for these queries, so the gap is minor.

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