Trainer Connect

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

Annotations already declare this is a non-read-only, non-destructive, open-world mutation. The description usefully adds the concrete side effect — the class is moved to the requested time — but says nothing about whether the move is reversible, what happens if the target slot is unavailable, or whether the student is notified.

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 sentence, front-loaded with the action and effect, with no filler. Its only shortfall is that brevity here comes at the cost of the missing behavioral and usage detail noted above.

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 with no output schema, the description covers the core effect but omits failure modes, side effects on the existing class, and confirmation behavior. It is minimally adequate rather than complete.

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

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

There is a single required parameter with 100% schema description coverage that already points to list_class_change_requests as the source. The description adds nothing about the id's semantics, so the baseline 3 for fully-covered schemas applies.

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

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

The description states a specific verb and effect: accepting a student's change request and moving the class to the requested time. This is clearly distinct from the sibling reject_class_change, though the description never names that alternative explicitly.

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

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

Usage is only implied: the agent can infer this is the 'approve' half of the accept/reject pair. There is no explicit statement of when to use it versus rejecting or rescheduling, and prerequisites (e.g., request must still be pending) are unstated.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is known. The description adds genuine value by disclosing the consequence — 'they get access to the app' — but omits reversibility (can access be revoked?), whether the student is notified, and what happens if the request is stale.

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 front-loaded sentence with the outcome tacked on, so nothing is wasted. The clause 'who asked to train with the trainer' is slightly redundant given the tool is about join requests, but it is not harmful.

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

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

For a one-parameter mutation with no output schema, the description covers the action and its effect, and annotations cover the write semantics. Missing only niche details such as notification behavior or error cases on a non-pending request.

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 a single parameter at 100% schema coverage, the schema already fully documents requestId and even points to list_join_requests as its source. The description adds nothing beyond that, so the baseline of 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 object ('Accepts a student') plus the source of the request ('asked to train with the trainer'), which maps onto the join-request domain. It implicitly contrasts with reject_join_request by naming the affirmative action, though it never names the sibling explicitly.

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

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

Usage is only implied: the schema note 'Id from list_join_requests' hints at the list-then-accept workflow, but the description itself never says when to call this versus reject_join_request or what preconditions must hold (e.g., a pending request). No exclusions or alternatives are stated.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false), so the description isn't carrying that burden. It does add genuinely useful side-effect context: the previously active plan is archived on publish. However, 'pushes them' is opaque — it doesn't say whether that is a notification, a delivery failure mode, or anything the agent should surface.

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 front-loaded sentence with no filler. The trailing 'and pushes them' is terse to the point of ambiguity, which is the only structural weakness.

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

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

For a one-parameter tool with annotations and no output schema, the definition covers the action and its archival side effect but leaves the 'push' undefined and says nothing about what is returned or what happens if publishing 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 100% and the single planId parameter is already documented as an id from list_diet_plans, so the schema does the work. The description adds nothing about the parameter, which is acceptable at this coverage level.

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 (publishes) and resource (diet plan) plus the target (the student), so the action is unambiguous. It does not differentiate itself from near siblings like schedule_diet_plan or get_active_diets, but the core purpose is clear.

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

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

The description gives no when-to-use or when-not guidance and names no alternative. The only routing hint, planId coming from list_diet_plans, lives in the schema rather than the description.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only that exactly one exercise is inserted, with no disclosure of whether 'name' creates a freeform/custom exercise, what happens on duplicates, or whether ordering within the day matters.

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 well-front-loaded sentence with no filler; the parenthetical '(or a range)' is the only mild redundancy against the reps_max schema description. Efficient, though it spends its space on field enumeration rather than the ambiguity that 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 an 11-parameter mutation tool with no output schema and 45% schema coverage, the description is thin: it omits phase, duration/notes semantics, and the name-vs-catalog-id relationship the agent must resolve 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 45% across 11 parameters; the description names sets, reps/rep-range, load and rest, which covers five fields but leaves name, notes, phase, duration and edb_exercise_id unaddressed. Crucially it never explains how the required 'name' relates to the optional edb_exercise_id, which is the most consequential ambiguity.

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 ('Adds one exercise to a training day of a program') plus the payload fields it handles. It is clearly distinguishable from siblings like add_program_day or add_program_week, though it does not name them.

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

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

There is no guidance on when to use this versus update_program_day or apply_catalog_workout, and no prerequisites. The description gives no indication of whether the target day must already exist or how to obtain a dayId (that hint lives only in the schema).

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 readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the write-but-not-destructive profile is already known. The description usefully adds that the write is scoped to the trainer's own favorites and changes ordering in workout building, but says nothing about idempotency or behavior when the exercise is already favorited.

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 sentence with the action front-loaded followed by the user-visible consequence; no redundant restatement of the title or schema.

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

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

For a single-required-parameter mutation with no output schema and annotations covering safety, the essentials are present. What is missing is a note on repeat calls (already favorited) and confirmation that no response payload is returned, which keeps it below a 5.

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

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

Schema coverage is 100% and the single parameter already documents its source (list_library_exercises or search_exercises). The description only reinforces that the ID refers to a library exercise rather than a custom/template exercise, adding marginal value beyond the schema; baseline 3 applies.

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

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

Names a specific verb (adds) and resource (a library exercise into the trainer's favorites) plus the downstream effect, so it is clearly distinct from list_favorite_exercises. It does not explicitly contrast with the read-side sibling or add_favorite_food, so it falls short of a 5.

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

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

The phrase 'library exercise' and 'shown first when building workouts' implies the context (curating workout-building picks) but never states when to use this versus alternatives, nor any exclusion such as already-favorited exercises. Usage must be inferred.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the non-destructive write profile is known. The description adds genuinely new behavioral context via the consequence (favorites rank first in diet plans), but says nothing about idempotency, permissions, or errors for an unknown food_id.

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 sentence, zero filler, and the effect ('shown first when writing diet plans') is packed into the same clause as the action. Nothing to trim.

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

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

For a one-param, non-destructive write with full schema coverage and annotations, the definition covers purpose and user-visible consequence adequately. Only the idempotency/duplicate-handling question is left open, which is minor at this complexity.

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

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

Schema coverage is 100% and the single parameter already documents its origin ('From search_foods'). The description adds no format, validation, or constraint detail beyond that, which matches the baseline for a fully documented single param.

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 (adds) and resource (a food to the trainer's favorites), plus the downstream effect of favorites appearing first in diet plans. That distinguishes it from list_favorite_foods and add_favorite_exercise without naming them explicitly.

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

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

Usage is implied through the stated benefit ('shown first when writing diet plans'), which hints at when a trainer would want this. There is no explicit when-not guidance, no mention of the listing sibling, and no note on whether re-adding an existing favorite is appropriate.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so safety is covered. But the description adds nothing about mutation behavior: whether an existing day on the same day_of_week is rejected or overwritten, whether days are reordered, or what identifier comes back. For a 6-param creation tool that is a real 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?

A single front-loaded sentence with no filler. It is efficient, but the brevity is partly under-specification rather than discipline.

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 6 parameters, no output schema and only partial annotation coverage, the description should say more: which fields are optional, how day_of_week collisions behave, and what the tool requires (an existing week from get_program). As written, an agent must infer all of this.

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% – warmup_notes, cooldown_notes and estimated_minutes are undocumented anywhere. The description mentions no parameters at all, so it does not compensate for the coverage gap or clarify semantics like day_of_week indexing beyond what the schema already says.

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 ("Adds") and resource ("a training day") plus its placement ("to a week of a program"), which distinguishes it from add_program_week (adds a week) and add_exercise_to_program_day (adds an exercise to a day). It stops short of naming those siblings explicitly.

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

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

No guidance on when to use this versus update_program_day (existing day) or add_program_week. The only hint that weekId must come from get_program lives in the parameter schema, not the description.

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

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

Annotations already declare a non-read-only, non-destructive mutation, so the safety profile is covered. The description adds the meaningful behavioral detail that new weeks append by default or can be inserted at a position. It does not say whether inserting shifts existing weeks, what an empty new week contains, or what is returned.

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

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

A single tight sentence with the key behavior front-loaded — no waste. Its brevity is efficient rather than padded, though it leaves the reader wanting the detail that the schema also lacks.

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?

A 4-parameter mutation tool with 25% schema coverage and no output schema needs more from the description: what the created week looks like, position bounds/shifting behavior, and what the response returns. Only the placement behavior is addressed.

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

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

Schema description coverage is only 25% — only programId is documented (via the schema). The description alludes to 'position' but says nothing about 'name' (required) or 'notes', and gives no ordering/index semantics for position (0-based? 1-based? out-of-range behavior).

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 ('Adds a week') and clarifies the default placement ('at the end of a program') with the optional override ('or at position'). It does not distinguish itself from close siblings like add_program_day or update_program_week, so an agent must infer the boundary.

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

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

No when-to-use guidance, no prerequisites (e.g., program must exist, ownership), and no mention of alternatives such as update_program_week for modifying an existing week. The only implied usage cue is the append-vs-position note.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation profile is covered. The description does add one genuinely non-obvious behavioral fact — the student receives reminders, i.e. a side effect outside the record itself. It stops short of duplicate handling, whether the regimen is recurring indefinitely, or permission requirements.

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

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

One compact sentence with the action front-loaded and no filler. The '(or water)' parenthetical earns its place by widening what can be registered, though the sentence tries to carry regimen facets and the reminder side effect at once.

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

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

For a 9-parameter creation tool with no output schema, the description covers intent and one side effect but omits what is returned (e.g. the new supplement id), duplicate behavior, and edit-vs-create routing. Adequate to start a call, not sufficient to call it confidently.

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

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

Schema coverage is only 44%, so the description must compensate and does so only partially: 'dose, times and days' maps to dose_amount/dose_unit, times and days_of_week. It says nothing about the ambiguous units_per_take, the name/type pairing, or notes, leaving several required fields unexplained in both schema and 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?

States a specific verb (registers) and resource (a supplement, or water, for a student) plus the regimen facets it captures (dose, times, days). It is clearly distinguishable from update_student_supplement and list_student_supplements by the create verb, though it never names those siblings explicitly.

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

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

No when-to-use or when-not guidance. An agent gets no signal on how this differs from update_student_supplement (editing an existing regimen) or when to check list_student_supplements first to avoid duplicates, and no prerequisites such as resolving studentId via list_students.

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 safety is covered structurally. The description adds real behavioral context beyond them: the call executes as the connected trainer and inherits the app's permission model ('Same permissions as the app'), and the response mirrors the app's JSON. Pagination, error behavior and rate limits remain undisclosed.

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

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

Two sentences, front-loaded with the mechanism ('Runs any GET operation...') before the resource enumeration. The long list of data types is dense but earns its place by defining the tool's scope for an agent deciding whether it can serve a given read.

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 while the description says the response is 'the same JSON the app gets' plus example resources, it does not describe pagination, error shape, or how the query object maps onto the underlying endpoint. For a generic path-based passthrough with a nested query parameter, that leaves meaningful gaps.

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

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

Schema coverage is 100%, so the schema already documents both parameters, giving a baseline of 3. The description adds meaning by naming the authoritative source for valid paths (list_operations) and by enumerating the kinds of resources reachable through it, which helps an agent construct a path rather than guess.

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: it runs any GET operation catalogued in list_operations and returns the app's JSON. The GET framing implicitly separates it from api_write, and it points at list_operations as the catalog of valid paths. It stops short of an explicit contrast with narrower sibling getters like get_student or get_schedule.

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

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

The description implies that the path argument is drawn from list_operations, which is useful routing context. However it never says when to prefer this generic passthrough over the dedicated siblings (get_student, get_schedule, list_payments, search_exercises), which is exactly the ambiguity an agent faces here.

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 destructiveHint/openWorldHint annotations: it discloses that the same permissions, plan limits and validations apply, that a 422 enumerates what is missing, that operations can trigger push/e-mail notifications to students, and that some are irreversible and should be confirmed first. This is exactly the context the 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?

Two sentences, front-loaded with the core capability and followed by the side-effect caveat and the exclusion list. Dense and every clause earns its place, though the long enumeration of example operations and excluded domains makes it a heavier read than strictly necessary.

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

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

For a generic escape-hatch write tool with three params and no output schema, it covers the discovery workflow, permission/validation behavior, error signaling (422), side effects, irreversibility, and scope boundaries. Nothing an agent needs before invoking it 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 100%, so the baseline is 3. The description adds value by tying method/path/body to their source (list_operations for method/path, describe_operation for body fields), which tells the agent how to populate them rather than just what they are.

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: runs any POST/PUT/PATCH/DELETE operation from list_operations as the trainer. The examples (archive workouts, assign programs, log sessions, send chat messages) and the explicit exclusion of payment/account operations make it distinguishable from api_read and the many single-purpose write siblings.

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

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

Explicitly routes the agent through list_operations and describe_operation before calling, and provides a concrete exclusion list (charges, refunds, subscriptions, plans, prices, coupons, tabs, withdrawals, bank details, password, account deletion) of things that must be done in the app instead. Both the when and the when-not are stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful effect note that students 'see it in the app' (a user-visible side effect), but says nothing about behavior when a copy already exists — relevant given the sibling tools list_workout_copies and sync_workout_copies.

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

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

A single compact sentence with the verb front-loaded and no filler. It is efficient, though that brevity is partly the cause of the guidance gaps elsewhere.

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 mutation tool with no output schema, the description omits what is returned or created per student, how duplicates are handled, and how day_of_week affects the copy. The agent is left guessing about the outcome of a write operation.

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

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

Schema coverage is only 67%; the two described fields just point at list_catalog_workouts and list_students. The description adds nothing about how day_of_week interacts with a copied workout (does it place the workout on a specific day?) — the one parameter that is undocumented in the schema and whose meaning is genuinely 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?

Specific verb (copies) plus resource (catalog workout) and target (one or more students), which separates it from list_catalog_workouts and get_catalog_workout. It does not, however, distinguish itself from copy_program or sync_workout_copies, which are the closest functional siblings.

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

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

The description states only what it does, never when to choose it over copy_program or sync_workout_copies, nor when not to use it. No prerequisites (must the workout be published? must students exist?) are given, leaving the agent to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the basic safety profile is covered. The description adds that the action is bulk and happens 'with one push,' but it does not clarify reversibility, what happens when no pending suggestions exist, or any permission requirements, so it adds only modest context beyond 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 definition is a single front-loaded sentence with no wasted text. It conveys the bulk scope and single-action nature immediately.

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 one-parameter bulk approval tool with a fully documented schema and no output schema, the description is largely complete. It could add a note about behavior when there are no pending suggestions or what 'one push' entails, but nothing essential to invocation 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 100% and the only parameter, student_id, is documented in the schema as coming from list_students. The description only says 'one student,' which does not add meaningful semantics beyond what the schema provides, so the baseline 3 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 (approves), resource (every pending workout suggestion), and scope (one student at once). The phrase 'every ... at once' implicitly distinguishes it from the singular sibling approve_workout_suggestion, so 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?

It clearly establishes the bulk-approval context: all pending suggestions for one student in a single action. It does not explicitly name approve_workout_suggestion as the alternative for individual approvals, but the intended usage is clear from the 'every ... at once' phrasing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is carried by structured fields. The phrase 'applies it to the exercise' usefully signals a mutation of the underlying workout, but the description says nothing about reversibility, notifications to the student, or what happens to concurrent suggestions.

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

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

One short sentence with the action front-loaded and no filler. It is efficient, though so terse there is spare room that could have been spent on preconditions.

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

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

For a one-parameter mutation with a fully documented schema and annotations covering safety, this is minimally adequate. The gaps are the mutation's scope (what exactly is overwritten on the exercise) and side effects, which matter for a write tool even when no output schema exists.

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 single parameter is already documented as an id sourced from list_workout_suggestions. The description adds no format, range, or validity information beyond that, so the baseline of 3 applies.

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

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

The description names a specific verb (approves) and resource (a student's suggestion) plus the effect (applies it to the exercise), which is far more informative than the title alone. It does not explicitly contrast with reject_workout_suggestion or accept_class_change, but the action is unambiguous.

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

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

Usage is implied by the approval semantics, and the schema note pointing at list_workout_suggestions gives the prerequisite discovery step. There is no explicit statement of when to approve versus reject, or of any precondition such as the suggestion still being pending.

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?

Adds real context beyond the annotations: the effect is visibility-scoped (student's history only) and non-destructive, which corroborates destructiveHint=false and readOnlyHint=false. It stops short of saying whether the assessment remains visible to the trainer/admin, whether the action is reversible via unarchive_assessment, or what permissions are needed.

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 sentence, zero waste, with the critical constraint ('without deleting it') placed after the core action. Nothing to trim or reorder.

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

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

For a single-parameter, non-destructive mutation with full annotation coverage and no output schema, the description is nearly sufficient. The only gap is not pointing at unarchive_assessment for reversal and not clarifying audience of the hidden state.

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

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

Only one parameter and schema coverage is 100% ('The id from list_assessments'), so the schema already carries the load. The description adds no extra meaning about the id, format, or provenance, which is acceptable at baseline for a single fully-described param.

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 (archive/hide) and resource (assessment) plus the key scope distinction 'from the student's history without deleting it'. An agent can distinguish it from a delete or an update, though it never names the closest siblings (update_assessment, unarchive_assessment) explicitly.

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

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

Usage is only implied: an agent can infer you archive instead of deleting when you want to keep the record. There is no explicit 'use this when... use X instead' guidance, no mention of unarchive_assessment as the reversal path, and no prerequisite conditions.

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

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

Annotations only tell the agent this is a non-read-only, non-destructive, open-world write. The description usefully adds that passing null clears the existing assignment, which is real behavioral value beyond the annotations. It still omits whether re-assigning an already-assigned student silently overwrites the previous member or errors, and whether the operation is idempotent.

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

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

A single compact sentence with the core action front-loaded and the null case trailing as a qualifier. Nothing is wasted, though it is terse enough that some structural detail (reassignment semantics) is absent rather than merely trimmed.

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 mutation with fully documented inputs and no output schema, the description covers the essential effect and the unassign case. It leaves out the outcome of reassigning a student who is already assigned to someone else, which is the main ambiguity an agent would face when calling it.

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, but the description goes further by explaining the semantic effect of the nullable member_user_id ('null removes it'), which the schema only describes as 'or null'. That added meaning about the null/clear behavior earns a point above 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 concrete verb+resource: making a team member responsible for a student, which is a distinct relationship-assignment action not duplicated by any sibling (list_team_members and list_students only supply ids). It is clear but does not explicitly contrast itself with adjacent student/team operations like update_student or invite_student.

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?

'null removes it' implies the unassign path, so an agent can infer both directions of use. However there is no statement of prerequisites (e.g. the caller must own the team), no mention of when to prefer this over other student-member operations, and no explicit 'do not use for X' 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?

The annotations already declare a non-read-only, non-destructive, open-world mutation. The description adds useful context that the assessment is a trial-class assessment without a student, but it does not disclose failure conditions, reversibility, or whether prior linkage is rejected.

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

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

The description is a single front-loaded sentence with no wasted text. It immediately conveys the state transition and the relevant domain context (trial class).

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 mutation with full schema descriptions and annotations, the description covers the core operation adequately. But it leaves behavioral gaps around preconditions, side effects, and result expectations that an agent might need before invoking it.

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 documents both parameters and points to list_students and list_unlinked_assessments. The description reinforces that the assessment is unlinked and becomes the student's first assessment, but adds little parameter-specific syntax or constraint detail beyond the schema.

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

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

The description uses a specific transformation verb and names both the source assessment state (without a student, trial class) and the target student relationship. It is distinguishable from sibling tools like create_assessment and link_assessment_to_class, though it does not explicitly name those alternatives.

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

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

Usage is implied: use this when an assessment has no student and should become that student's first assessment. However, the description does not explicitly state when not to use it, what to do if the assessment is already linked, or which sibling tools handle related cases.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds a genuine behavioral fact beyond them: the action is effectively one-way because unblocking happens in the app, not through MCP. It does not cover idempotency or what happens to existing message history, which keeps it from a 5.

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

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

Two short sentences, front-loaded with the effect and followed by the unblock routing note; nothing is filler. The phrase 'in the app' is slightly vague about which surface, but the structure is efficient.

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

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

For a single-parameter mutation with annotations and no output schema, the description supplies enough to invoke it correctly, and the unblock note covers the main follow-up question. Success/failure behavior and any permission requirements are left implicit.

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 single otherUserId parameter is documented there as the student's user id, so the schema carries the burden. The description adds no format, lookup, or constraint detail beyond that.

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

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

The definition uses a concrete verb and resource combination ('stops a person from sending messages to the trainer') and states the direction of the block, which differentiates it from read-only siblings like get_chat_block_status. It stops short of naming that sibling explicitly, so the boundary must be inferred.

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 clause 'Unblocking is in the app' usefully implies there is no complementary API tool, but there is no explicit when-to-use guidance, no mention of get_chat_block_status for checking current state, and no stated preconditions such as whether the target must already be a student.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the student receives a push notification and the effect mirrors the in-app action. It stops short of stating reversibility or failure behavior, which is what keeps it from a 5.

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

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

Two short clauses, front-loaded with the action and followed by the side effect and the confirmation requirement. "Like in the app" is slightly loose but earns its place by anchoring the behavior to a known surface.

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

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

For a destructive, single-parameter tool with full annotations and full schema coverage, the description covers what gets affected (student notified) and the pre-call safety step. No output schema exists, so unexplained return values are acceptable.

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

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

Schema coverage is 100% and the single parameter is already documented as "Appointment id from get_schedule", a useful cross-reference the description does not need to repeat. The description adds nothing about parameter meaning, so the baseline 3 is correct.

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

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

The description opens with a specific verb+resource, "Cancels a class", which an agent can distinguish from reschedule_class or confirm_class. It never names those siblings explicitly, so differentiation is inferred rather than stated.

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

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

"Confirm with the person first" is a genuine usage precondition that tells the agent to verify the human before invoking. However, it gives no guidance on when to cancel versus reschedule_class or reject_class_change, so the alternative-selection decision is left unaddressed.

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?

'Saves nothing' is useful behavioral context (the check does not reserve or persist the slug, so it cannot guarantee later availability), but it sits in tension with readOnlyHint=false, which declares the tool is not read-only. The description also says nothing about what a positive/negative result looks like or whether the check is authoritative.

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 very short sentences, front-loaded with the core question the tool answers and followed by the one behavioral caveat. 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?

A single-parameter, no-output-schema tool is nearly fully covered by 'tells whether ... is free.' The one gap is the tension around side effects and what the returned answer looks like, but for this complexity level the description is close to sufficient.

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 already specifies the allowed character set, so the schema carries the parameter burden. The description only adds the framing that the slug is the public page address; it adds no format or constraint detail beyond the schema. 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 object: tells whether a slug for the public page is free. An agent immediately knows this is an availability check, not a create/update. It does not explicitly distinguish itself from nearby siblings like update_public_profile or get_public_profile, so it falls short of a 5.

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

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

Usage is only implied: the natural reading is 'call this before setting a public page address.' No explicit when-to-use, when-not-to-use, or named alternative is given, so the agent must infer the workflow context.

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=false but leave readOnlyHint=false; the description's 'Changes nothing' supplies the crucial safety fact the agent needs (this lookup is side-effect free) despite the default read-only flag. It does not say what the tool returns or how a 'no account' case is expressed, which the agent must know to act on the result.

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?

Very short and front-loaded: the check is stated first, the timing guidance second, the no-side-effects guarantee last. The fragmentary opening sentence is slightly awkward but wastes no words.

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

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

With no output schema, the description should indicate whether the answer comes back as a boolean, found/not-found status, or a student record. As written, the agent knows what to ask but not how to interpret the response, which is a meaningful gap for a lookup 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?

One required parameter with 0% schema description coverage, so the description carries the burden: it makes clear the input is an e-mail address of a prospective student. Nothing is said about format or validation, but the semantics are fully inferable.

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 behavior: testing whether an e-mail already has an account in Trainer Connect. It distinguishes itself from the invite flow by framing itself as a pre-check. It is slightly indirect (a 'Whether...' fragment rather than a verb like 'Check'), but the intent is unambiguous.

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

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

'before inviting the student' gives a concrete trigger point and implicitly points at invite_student/create_student as the follow-up action. No explicit when-not or edge-case handling is given, but the calling context is clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is known without the description. The description adds nothing beyond that: it does not say what is returned, whether the comment is publicly visible, whether the idea must already exist, or any length/permission constraints on posting.

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

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

A single short sentence with zero filler and the verb-action front-loaded. It is efficient, though the brevity reflects under-specification rather than disciplined editing.

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?

This is a simple two-parameter mutation with no output schema, so the definition is minimally sufficient — annotations carry the safety profile and the schema carries the parameter names. Still, for a write tool the description should confirm the effect (comment is posted to the idea identified by ideaId) and whether it is publicly visible; that omission leaves a 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 coverage is 50%: ideaId is documented at the schema level while body is bare but self-explanatory in meaning. The description contributes no parameter detail at all, so the baseline of 3 applies — adequate, with the residual gap being content/length constraints on the comment body.

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 ('Adds a comment to an idea'), which is clearly distinguishable from vote_feature_request, suggest_feature, and get_feature_request in the sibling list. The only weakness is terminological drift: it says 'idea' where every sibling uses 'feature_request', so the agent must infer they are the same object.

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

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

No guidance on when to use this versus adjacent tools (vote_feature_request, suggest_feature, get_feature_request, list_feature_requests) appears anywhere in the description. The only routing hint in the whole definition lives in the schema ('Id from list_feature_requests'), not in the description itself.

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

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

Annotations already disclose that this is a non-read-only, non-destructive, open-world operation. The description adds the prerequisite that the class is waiting for confirmation, which is useful behavioral context, but it does not describe the resulting state change, permissions, or external side effects.

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

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

The description is a single front-loaded sentence with no wasted text. It is appropriately sized for a simple one-parameter tool.

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

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

For a simple one-parameter mutation with full schema coverage and useful annotations, the description provides enough context to invoke the tool correctly. It is only slightly incomplete because it does not clarify how this differs from sibling tools that also accept or reject class-related requests.

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 appointmentId parameter is already documented as coming from get_schedule. The description does not add any further meaning about the parameter, so the baseline score of 3 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: accepting a student-booked class that is awaiting confirmation. It is clear enough for an agent to understand the action, but it does not explicitly distinguish this from nearby siblings such as accept_class_change or reject_class_change.

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 phrase 'waiting for confirmation' implies the condition under which this tool applies, giving basic usage context. However, it does not state when not to use it or name an alternative sibling for change-request scenarios.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation profile is known. The description adds that omitting student_id yields a new template — a useful non-obvious side effect — but says nothing about what gets duplicated, whether the copy is independent of the source, or the result payload.

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

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

A single sentence, front-loaded with the verb and both modes, with zero filler. Nothing could be cut without losing 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 three-parameter copy operation with no output schema, the description covers the essential decision (target student or template) and the source lookup is documented in the schema. Missing is any statement of what the tool returns (e.g., the new plan id) and the role of title, which matters for a mutation 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 coverage is 67% and the source parameter (planId) plus student_id are already documented in the schema. The description clarifies the semantic effect of student_id (target student vs. template mode), but the title parameter has no description anywhere and is never mentioned, leaving one of three parameters undefined.

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 (copies) and resource (diet plan/template) and crisply distinguishes two operating modes based on the presence of student_id. It does not name the sibling tools it competes with (copy_program, schedule_diet_plan, create_diet_plan), so it stops just short of a 5.

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

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

The description gives a clear, actionable rule: pass student_id to copy to a student, omit it to save as a template. That is real usage guidance for the branch point an agent faces. It doesn't say when to prefer this over schedule_diet_plan/activate_diet_plan or create_diet_plan, so no exclusions.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so safety is already covered. The description usefully explains the template-vs-student branch, but says nothing about what content is duplicated (days, weeks, exercises), whether the copy inherits published state, or permission requirements.

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

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

One sentence, no filler, and the branching condition is front-loaded right after the verb. Every clause earns its place.

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

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

Adequate for a 3-parameter mutation with no output schema, but incomplete in ways that matter for calling it correctly: what gets copied, whether the copy is draft or published, and default naming behavior are unstated.

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%, yet the description adds real meaning: omitting student_id is what produces a template, which the schema's "The student_id from list_students" does not convey. The optional name parameter is left unexplained (e.g. default naming).

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 ("Duplicates") and resource ("a program"), and the same sentence distinguishes the two modes of the operation. An agent can tell this apart from create_program (new program) 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 clear selection rule tied to the input: pass student_id to copy for another student, omit it to create a new template. It stops short of exclusions or prerequisites, e.g. whether the source program must belong to the caller or be published.

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, open-world, non-destructive mutation, so the safety profile is covered. The description adds the notion of responding to a request with an alternative time, but it doesn't explain what happens to the original request, whether the student is notified, or whether the request remains pending.

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

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

The description is a single front-loaded sentence with no filler. It is efficient, though its brevity contributes to the under-specification noted elsewhere.

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 mutating workflow tool with no output schema, the description omits important context: the state transition of the request, whether a note is sent, and what happens after the counter-proposal. Annotations cover mutation safety, but the description does not fill the remaining gaps.

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

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

Schema description coverage is 75%, with good descriptions for requestId, response_note, and the ISO 8601 requirement for proposed_date_time. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies given the relatively high coverage.

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: answering a student's class change request with an alternative time. It clearly conveys a counter-proposal action, though it doesn't explicitly differentiate itself from close siblings like accept_class_change or reschedule_class.

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

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

There is no guidance on when to use this versus accept_class_change, decline_class, reject_class_change, or reschedule_class. The only implied context is that it applies to class change requests, with no exclusions or prerequisites stated.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is given. The description usefully adds that creation does not itself send the questionnaire, but says nothing about whether the new form is immediately active (a toggle_anamnesis_form sibling exists) or how send_to_new_students changes that.

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 clauses, front-loaded with the action, zero filler; the semicolon pointer to the sibling is efficient. It is, however, terse to the point of omitting things the agent needs, so it is concision at the edge of under-specification.

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 four parameters, a nested fields array and no output schema, the description does not tell the agent what is returned (crucially, the form identifier needed to call send_anamnesis) or how the field objects map to questions. For a create tool in a multi-step workflow, that is a substantial 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 only 25%, and the description adds no parameter meaning at all: it never mentions title, the fields array structure, or that options are needed for select/radio/checkbox field types. The agent must infer the whole form-authoring contract 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 a specific verb and resource ("Creates a health questionnaire") and explicitly separates itself from send_anamnesis, which is the only sibling that could be confused with it. An agent can tell create vs. send vs. list/get 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?

The sentence "send_anamnesis sends it to a student" tells the agent that authoring and distribution are two steps, which is the key routing decision here. It stops short of stating when-not to use it or that existing forms should be modified with update_anamnesis_form 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 readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the useful behavioral fact that unspecified measurements may be omitted rather than defaulted, but says nothing about what happens on duplicate dates, whether this appends to an existing assessment, or what the response contains.

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

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

A single compact sentence plus a short imperative, with the resource and field list front-loaded and no filler. The efficiency is good, but the skinfold reference points at fields that don't exist in the schema, which slightly undermines the density.

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 20-parameter mutation tool with no output schema, the description covers only a subset of the accepted fields and never states what happens on success or failure. Combined with thin annotations, an agent still lacks enough information to call this confidently across all 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 only 10%, so the description must compensate and it partially does: it supplies units (cm for circumferences, mm for skinfolds) that the schema lacks entirely. But it omits half the parameters (height_cm, muscle_mass_kg, resting_heart_rate, notes, systolic/diastolic pairing) and even references skinfolds that have no corresponding schema property, leaving many fields undocumented anywhere.

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 ('Saves a new physical assessment for a student') and enumerates the measurement categories it accepts, so the agent knows exactly what this creates. It does not explicitly contrast with update_assessment or attach_assessment_to_student, though the create/update distinction is inferable from the name.

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

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

'Send only what was measured' gives real guidance on partial payloads, which is the main usage ambiguity for a 20-parameter tool with 2 required fields. However, there is no guidance on when to use this versus update_assessment for an existing record, nor on prerequisites such as the student already existing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so safety is largely covered. The description adds one valuable behavioral fact — the 20-question cap. It omits whether the template is created in draft or active state, whether it is immediately sendable, and any permission/quota requirements, which matters since openWorldHint=true suggests server-side side effects.

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

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

A single sentence with zero filler, front-loading the action and its key constraint before the routing hint. Nothing here could be removed without losing 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 creation tool with 5 params, no output schema and openWorldHint=true, the definition is thin on what comes back — an agent doesn't know whether it receives a template ID needed downstream for send_checkin. Annotations and inline schema cover the rest, so this is adequate but not complete.

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

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

Schema coverage is 60%: send_time, frequency_days and send_day_of_week are documented inline, but the two required params (name, questions) have no schema descriptions. The description only contributes the question-count cap; it says nothing about name uniqueness, whether questions is ordered, or how send_time/frequency_days combine to define the period.

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 ("Creates a periodic check-in") plus a concrete constraint (up to 20 questions). It separates itself from send_checkin, the assignment sibling, but does not distinguish itself from update_checkin_template or create_anamnesis_form, which are also creation/edit surfaces for questionnaires.

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 clause "send_checkin assigns it to students" implies the workflow split — create here, assign there — which is genuinely useful routing. However, it never says explicitly when to choose this over update_checkin_template or create_anamnesis_form, and there are no stated prerequisites.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation/safety profile is covered. The description adds only that scoring is per workout and per minute; it does not say whether students are auto-enrolled, whether the competition is global or scoped, or what limits apply.

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

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

A single tight sentence with no filler, and the core action is front-loaded. It is efficient, though the brevity contributes to the missing usage and behavior detail.

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

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

For a 6-parameter mutation with no output schema, the description omits return information, side effects on students, and validation rules (start_date 'today or later' lives only in the schema). It is not sufficient for an agent to call this confidently.

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

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

With only 33% schema coverage, the description partially compensates by naming the two scoring parameters (points_per_workout, points_per_minute). It says nothing about the optional 'description' parameter or the meaning of the required 'name', leaving a real 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 concrete verb and resource ('creates a challenge among students') plus the scoring basis. However, it calls the resource a 'challenge' while the tool name and siblings (get_competition, list_competitions, invite_to_competition) use 'competition', which muddies identification. No differentiation from those siblings is given.

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

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

There is no guidance on when to use this versus invite_to_competition, list_competitions, or create_workout/create_program. Prerequisites (e.g., whether students must exist first or are invited separately) are absent.

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=false, destructive=false), the description discloses the draft lifecycle and the tool required to publish — genuinely useful state information. It says nothing about whether targets are validated, what happens to an existing plan, permissions, or the response payload, and the meal-replacement behavior appears only in the 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?

Two sentences, front-loaded with the action and followed by the lifecycle caveat. Nothing redundant; every clause adds decision-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 an 8-parameter write tool with a nested meals array and no output schema, the description covers creation intent and publication state but leaves the bulk of the contract (targets, meal semantics, replacement behavior) to the schema. Adequate, but thin for its complexity.

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

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

Schema description coverage is only 25% on 8 parameters, so the description needs to carry more weight. It clarifies student_id as optional-with-consequence (template mode), but the four target_* parameters, notes, and meal structure get no meaning from the description at all.

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

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

A concrete verb plus resource ("Writes a diet plan with meals and foods") with the student_id/template distinction spelled out, which is more than a restatement of the title. It does not explicitly separate itself from update_diet_plan or copy_diet_plan, which an agent must infer from the create semantics.

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?

"Or a template without it" states the condition for omitting student_id, and "It starts as a draft: activate_diet_plan publishes it" names the follow-up tool and the state the object lands in. No explicit when-not or prerequisites (e.g. student must exist, foods come from search_foods), 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a genuine behavioral trait beyond that structure: duplicate names do not error and do not create a second record, they return the existing one, which is effectively name-based idempotency the agent would otherwise have to guess. It does not say anything about which account/library context is written to or what the returned record contains.

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

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

Two short sentences, no filler, with the dedup behavior front-loaded immediately after the core action. Nothing is repeated from the title or annotations.

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

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

For a single-parameter creation tool with no output schema, the description covers what it does, where it writes, and the one surprising edge case. The remaining gap is the return value's shape: an agent can't tell from the description whether the response includes the equipment id it would need for a follow-up rename_equipment call, only that 'the existing one' is returned.

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

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

With one parameter and 0% schema description coverage, the description has to carry the semantics, and it does add one important fact: 'name' is the identity/uniqueness key, so supplying an existing name resolves to that existing record instead of failing. It does not state constraints on the name (length, allowed characters, whether it must be unique only within the trainer's library, or how fuzzy the match is). Partial compensation, so a 3.

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

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

The description names a concrete verb (adds) and resource (a piece of equipment) and pins the destination scope ('their own library'), which distinguishes it from catalog-oriented siblings like list_catalog_categories or search_exercises. It doesn't explicitly name rename_equipment or list_library_equipment as related tools, but the scope wording carries enough signal to pick it out of the sibling list.

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

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

The phrase 'to their own library' implies when to use this rather than a catalog operation, and the duplicate note implies an agent does not need to pre-check existence. However, there is no explicit when-to-use/when-not statement or named alternative (e.g. 'use list_library_equipment first to check, use rename_equipment to change'). Usage is inferable rather than stated.

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

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

The annotations already declare this is a non-read-only, non-destructive, open-world write operation. The description adds that the saved exercise can include instructions and an optional video link. It does not explain creation side effects, duplicate handling, required permissions, or what is returned after saving.

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 definition is a single front-loaded sentence with no filler. It states the core action first and then adds relevant content details. It is concise, though perhaps too sparse for a seven-parameter creation 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 seven parameters, low schema coverage, and no output schema, the description should carry more context. It does not explain required fields beyond the schema, how to obtain equipment or muscle-group IDs, what happens after creation, or how this differs from updating an existing exercise template.

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 29%, so the description needs to compensate for several undocumented parameters. It mentions instructions and video_url but does not clarify name, description, image_url, equipment, or muscle_groups; the complex equipment and muscle_groups parameters are only explained by their 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?

The description states a clear action and resource: it saves an exercise in the trainer's library, with instructions and an optional video link. This is more specific than a tautology. However, it does not distinguish this create operation from sibling tools such as update_exercise_template or add_exercise_to_program_day.

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

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

The description implies this tool is for adding an exercise to the trainer's library, but it gives no explicit when-to-use guidance. It does not mention alternatives such as update_exercise_template for edits or add_exercise_to_program_day for assigning exercises to a program.

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

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

Annotations already declare a non-read-only, non-destructive create with openWorldHint, so safety is covered. The description adds genuinely useful behavior not in the annotations: values are per 100 g, and dish macros are computed by summing ingredients. It omits what happens when both macros and ingredients are supplied, permissions, and whether the created record is returned.

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

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

A single dense sentence with the creation mode front-loaded and no filler; the parenthetical about summed macros earns its place by explaining computed output.

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

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

For a 9-parameter mutation with no output schema and zero schema coverage, the definition is thin: an agent still doesn't know the unit/format for category, whether macros and ingredients are mutually exclusive, or what identifier comes back. The two authoring modes it does describe are the most important omission it fixes, keeping it at minimum-viable rather than inadequate.

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 9 parameters at 0% schema description coverage, the description carries the full burden and only partially meets it. It explains the per-100 g unit convention and the ingredients summing behavior, but says nothing about category, sodium_mg, fiber_g, portion_label, quantity_grams, or the required/optional split.

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 ('Adds a food') and distinguishes two creation modes: a food described by per-100 g macros, or a dish composed from ingredients. It does not name the sibling it contrasts with (update_food for edits, search_foods for finding food_ids), so sibling differentiation is only implicit.

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

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

The two-mode phrasing ('with macros per 100 g, or a dish from ingredients') gives an agent an implicit branch for how to call it, but there is no explicit when-to-use versus update_food instead of create, and no stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the conceptual meaning of each goal type (e.g. 'frequency (per week)', 'load (target kg in one exercise)'), which the annotations do not provide, but it says nothing about duplicate handling, validation failures, or whether the goal is editable afterward.

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

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

A single front-loaded sentence with zero filler; the type meanings are packed into parentheticals rather than spread across paragraphs. Slightly dense as a fragment, but every clause earns its place.

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

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

With 7 parameters, no output schema, and a mutation that is not destructive, the description covers the type dimension adequately but omits relationship context an agent would need: how this differs from update_goal, whether goals can coexist, and what is returned on success. Adequate but with clear gaps.

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

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

Schema description coverage is 86%, so a baseline of 3 applies, but the description genuinely adds meaning the schema lacks: the enum members are undocumented in the schema, and the description defines each one (workouts = count, frequency = per week, load = kg on one exercise). It does not add anything about start_date/end_date semantics, which the schema already covers.

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

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

States a specific verb plus resource ('Creates a goal') and immediately enumerates the four supported goal types, so an agent knows exactly what will be created. It does not differentiate itself from siblings like update_goal or set_weekly_target, which is the only reason it falls short of a 5.

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

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

There is no guidance on when to use this versus update_goal, set_weekly_target, or list_student_goals, and no mention of prerequisites (e.g. that studentId must come from list_students) or what happens if a goal of the same type already exists. Usage is only inferable from the verb 'create'.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond that - the account-owner-only authorization requirement - but says nothing about duplicate-name handling, limits on unit count, or what is returned.

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

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

Two sentences, front-loaded with the action, zero filler. The terse fragment "Only the account owner can." is slightly clipped but still earns its place by adding an authorization rule.

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?

A mutation tool with no output schema and fully undocumented parameters needs the description to explain inputs and side effects, and it does neither. It covers purpose and authorization but leaves an agent unable to know what a valid call looks like or what comes back.

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

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

Schema description coverage is 0% for both parameters, so the description carries the full burden, yet it never mentions 'name' (required) or 'address' (optional) or any format constraints. The parameter meanings are only guessable from the property names themselves.

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 (adds) and resource (a unit/branch of the gym), with the parenthetical clarifying what a "unit" means. It is clearly the create counterpart to the sibling list_gym_units, though it never names that sibling explicitly.

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

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

No indication of when to use this versus other setup tools, no prerequisites beyond the owner restriction, and no mention of related operations such as list_gym_units or how units relate to schedule slots. Usage is only inferable from the verb.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the effect is on the trainer's schedule rather than a global calendar, but does not say whether blocking is absolute, whether existing scheduled classes are cancelled or flagged, and what happens on overlapping dates or recurring dates across years.

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

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

One short sentence with the effect and scope front-loaded and no filler. It is efficient, though arguably too terse given the tool mutates scheduling state.

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-parameter create tool whose annotations already state the mutation and openness profile, and with fully documented parameters, the description covers what the tool does to the schedule. What is missing — conflict handling with existing classes and how a different managing trainer's view is affected — is useful but not required 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 100%: date format YYYY-MM-DD, name example, and 'Every year' for is_recurring are all documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

The description gives a concrete verb and effect ('blocks a date') plus the resource ('the trainer's schedule') and parenthetical examples tying it to vacation/holiday. It is clearly distinguishable from most siblings, but it never distinguishes itself from the closely related update_holiday or list_holidays, nor from create_schedule_slot, which also writes to the schedule.

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

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

There is no guidance on when to use this versus alternatives such as update_holiday (modify an existing block) or create_schedule_slot. No prerequisites, no exclusions, no mention of what happens if a class is already scheduled on the date being blocked.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the saved meal is a reusable library object, but says nothing about duplicate-name behavior, ownership/scope, or whether the created template is immediately usable in a diet plan.

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

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

A single tight sentence with no filler, and the object being created is front-loaded. It is efficient but borders on under-specified given the nested items payload.

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 create tool with a nested items array, four parameters and no output schema, the description covers the basic shape but not the item payload semantics (catalog food vs custom food, macro fields) or what identifier comes back for reuse. Annotations carry the mutation profile, but meaningful context is still 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 50%, and the description names three of the four top-level parameters (name, time, foods/items), which helps map intent. However it says nothing about the 'notes' field or about the item-level choice between food_id and custom_name, so it only partially compensates for the coverage gap.

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

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

States a concrete verb ('Saves') and a concrete resource ('a reusable meal'), and enumerates what the template holds (name, time, foods). It is clear what the tool produces, though it does not explicitly differentiate itself from create_diet_plan or update_meal_template in the sibling list.

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

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

The phrase 'to drop into diet plans' implies the intended workflow (build a reusable meal first, then reference it in a plan), but there is no explicit when-to-use, no mention of list_meal_templates/update_meal_template as alternatives, and no statement about prerequisites such as needing a food_id.

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

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

The description adds two facts not present in the annotations: writes go to the trainer's own library (ownership scope), and a duplicate name returns the existing record rather than erroring. That dedupe behavior is genuinely non-obvious and useful for an agent. It doesn't cover validation errors or response shape, so not a 5.

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

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

Two tight sentences with no filler; the action and scope are front-loaded and the duplicate-name rule follows immediately.

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

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

For a one-parameter write tool with no output schema, the return contract matters, and the description only implies the return (the existing record on collision) without saying what a successful create returns. Annotations cover the safety profile, so this is the main remaining gap.

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

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

Schema coverage is 0% for the single 'name' parameter, so the description has to compensate. 'If the name is taken' does convey that the name is a unique key and that collisions are deduped, which is real added meaning, but nothing is said about format, trimming, or naming constraints.

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 ('Adds') and resource ('a muscle group') plus scope ('the trainer's own library'), which separates it from rename_muscle_group, list_muscle_groups and list_library_muscles. It stops short of naming a sibling tool explicitly, so it lands just below the top tier.

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 create intent is clear from 'Adds', and the duplicate-name behavior hints at when calling it is safe, but there is no explicit statement of when to prefer this over rename_muscle_group or list_muscle_groups. Usage is only implied.

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

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

Annotations already declare this is a non-read-only, non-destructive, open-world write, so the safety profile is covered. The description adds the useful behavioral fact that the entire nested tree (program → weeks → days → exercises) is created in one call and that structure can be extended afterward. It says nothing about what is returned (e.g. a new program id needed for follow-on calls) or whether status defaults to draft.

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

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

Two sentences, front-loaded with the action and resource, with the mode switch immediately following. The parenthetical structure is dense but every clause carries information; no filler.

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

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

For a 7-parameter nested create with no output schema, the definition conveys the creation model but omits what the agent gets back and how status/difficulty affect the result. An agent can form a reasonable call from it, but would have to guess at downstream wiring (program id) and default status.

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 14%, so the description carries most of the burden, yet it only explains student_id and the general weeks concept. The top-level parameters status (draft vs active), category, difficulty, and the program-level description field get no semantic treatment in either place, and the meaning of a draft program versus an active one is left entirely unstated.

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 ("Creates a program") and clarifies the payload shape (weeks with training days and exercises) plus the two modes: student-bound via student_id or a standalone template. It does not distinguish itself from create_workout or the incremental add_program_week/add_program_day siblings, so an agent must infer which builder to pick.

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

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

The clause "or as a template without it" gives a concrete rule for omitting student_id, which is real usage guidance. However, "Weeks and days can also be added later" only hints at the incremental alternative (add_program_week/add_program_day) without naming it, and nothing explains when to use create_program versus create_workout or copy_program.

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-destructive write in an open-world domain, so the safety profile is handled. The description adds that slots recur weekly, but says nothing about overlap/conflict handling, permission requirements, or what happens when an identical slot already exists — relevant for a recurrence-creating 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?

A single front-loaded sentence stating what is created and the one branching semantic that matters. No filler, no repetition 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?

Seven parameters at 43% coverage and no output schema mean the description should carry more weight. It covers the key student_id branch but leaves the time/day/duration semantics and conflict behavior unaddressed, which is enough for a basic call but not for confident 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 only 43%, so the description needs to compensate and mostly doesn't. It explains only student_id (and its omission meaning), leaving day_of_week, start_time, duration_minutes, title, location and is_online with no extra meaning beyond the sparse schema.

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

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

States a specific verb and resource ('Adds a recurring weekly class slot to the trainer's schedule') and clarifies the two modes: for a student, or a personal block when student_id is omitted. It never names the nearest siblings (schedule_class, update_schedule_slot, list_schedule_templates), so an agent must infer the boundary itself.

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

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

The student-vs-personal-block distinction is implied usage guidance, but there is no explicit when-not or alternative. Nothing tells the agent whether one-off sessions belong in schedule_class instead, or how this relates to update_schedule_slot for later edits.

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

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

Annotations already declare the write/safe profile (readOnlyHint=false, destructiveHint=false), and the description adds genuinely new behavior: an e-mail invite is sent and the plan's student limit is enforced. It stops short of describing what happens when the limit is exceeded or what identifier is returned.

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

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

Purpose and side effect are front-loaded in the first clause, followed by required/optional fields and the plan constraint. The app-UI analogy ('like "Adicionar aluno"') is a small amount of filler but does not obscure the core 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?

With no output schema and only high-level annotations, the description covers the mutation's side effects, required inputs, and a key constraint, which is close to sufficient for an agent to call it correctly. Missing details are the response shape and limit-exceeded failure 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 88%, so the schema already documents each field including formats like YYYY-MM-DD and the email invite target. The description mostly restates the required/optional split that the schema's 'required' array already conveys, adding little 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?

Names a specific verb and resource ('Adds a student to the trainer's account') and immediately characterizes the effect: an e-mail invite to install the app. It is clearly distinct from sibling creation tools like create_workout and schedule_class.

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

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

States a real precondition ('Respects the student limit of the trainer's plan') and which fields are required vs optional, giving the agent clear context for when the call will succeed. It does not, however, name alternatives such as get_student for lookups or say what to do when the plan limit is hit.

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, open-world write, so the safety profile is covered. The description adds useful scoping context — that the goal becomes a selectable option in the trainer's picklist — but says nothing about duplicate-name handling, validation, permissions, or what is returned, which matters for a create operation.

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

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

A single front-loaded sentence with the resource, the effect, and a concrete example. No filler or redundancy.

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

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

For a one-parameter create tool with annotations present and no output schema, the description covers the core intent but leaves gaps: whether an existing goal with the same name causes an error, and what the call returns (e.g., the created goal with its id for later rename_training_goal calls).

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

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

Schema coverage is 0%, so the description must compensate, and it partially does by giving an example ('Corrida de rua') that implies the parameter is a human-readable display label. It does not state constraints such as uniqueness, max length, or whether the name is user-visible/localized.

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

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

Specific verb+resource ('Adds a training goal') with a concrete example value ('Corrida de rua') and the qualifier 'to the options the trainer picks from', which clarifies this creates a catalog option rather than assigning a goal to a student. It does not name the near-siblings create_goal or list_training_goals explicitly, so differentiation is inferred rather than stated.

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

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

Usage is only implied: the agent can infer this is for adding a new selectable goal option, but the description never states when to use this versus create_goal, update_goal, or rename_training_goal. No prerequisites, no exclusions.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds non-obvious side effects the annotations cannot express: the student is notified, and each exercise is matched by name to the Trainer Connect library so the demo video appears. It doesn't discuss failure behavior on unmatched names, but the added context is real.

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 that front-loads the core action and mode distinction, then layers weekly-program and exercise-matching guidance. Slightly packed, but every clause carries operational detail rather than filler.

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

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

With no output schema and 7 params at full coverage, the description supplies the missing behavioral layer: notification side effect, the template-vs-student branch, and the multi-call weekly-program pattern. It omits error handling for unmatched exercise names, which is a minor gap for a create 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, but the description adds relational meaning the schema lacks: reps and reps_max combine into a range, duration is for cardio, weight is load, and edb_exercise_id is an alternative to name-based library matching. This clarifies how the flat fields interact, which the schema alone 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 ('Creates a workout') and immediately distinguishes its two modes: assigned to a student via student_id, or a library template when student_id is empty. An agent can tell this apart from siblings like create_student or schedule_class 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 concrete usage context: pass edb_exercise_id from search_exercises if the library match is wrong, and call once per day with the same program name plus day_of_week for a weekly program. It names the relevant sibling (search_exercises) but stops short of explicit when-not-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 already declare readOnly=false, destructive=false, openWorld=true. The description adds genuinely new context beyond that: the link is temporary, works on web and app, and grants the recipient the ability to see AND copy the workout — an important exposure consequence. It omits the default TTL when ttl_minutes is omitted and whether links are revocable.

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

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

Two short sentences, front-loaded with the effect of the call and then the input rule. No filler.

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

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

With no output schema, the agent is left guessing what the response contains (the URL, its expiry, a token). The description establishes the concept of a link but not its return shape, default validity, or whether sharing requires the workout to be published.

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 earns above baseline by clarifying that exactly one of workout_id or workout_day_id is expected (an 'or' relationship the schema leaves ambiguous, since required is empty and both are optional). It still doesn't say what happens if both are supplied or what TTL defaults to.

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: creates a temporary link for sharing a workout or one program day. Scope (workout vs. single program day, web and app) is clear. It does not differentiate from nearby siblings such as get_invite_link or check_public_link, so it stops short of a 5.

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

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

The only guidance is 'Send workout_id or workout_day_id', which is parameter-level, not when-to-use. There is no statement of prerequisites (must the workout exist/published?) or when to prefer this over get_invite_link or check_public_link.

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 that this is a non-read-only, non-destructive mutation. The description adds meaningful behavioral context beyond them: the student is notified and only pending bookings are affected.

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

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

It is a single front-loaded sentence with no wasted text. The key action and state constraint appear immediately.

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 one-parameter mutation with annotations and full schema coverage, the description covers the action, precondition, and side effect. It does not mention return behavior, but no output schema exists and this is a minor gap.

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

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

There is one parameter with 100% schema description coverage, and the schema already says the appointmentId comes from get_schedule. The description adds no further parameter semantics, which is acceptable at 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: declining a class booking that is waiting for confirmation. It clearly distinguishes the pending-confirmation state, though it does not explicitly name sibling tools like cancel_class or confirm_class.

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

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

It gives a clear usage condition: the booking must be waiting for confirmation. It does not explicitly state when not to use it or name alternatives, but the condition is specific enough to guide selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral value by disclosing what the call returns (route params plus per-field validation rules), which matters because there is no output schema to explain the response shape.

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

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

Two tight sentences: the first states what is returned, the second states when to call it. Nothing is padded and the payload (fields and validation rules) is front-loaded.

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 introspection tool with full schema coverage, the definition covers purpose, timing and return content. With no output schema present, the description's explanation of returned validation rules fills 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 coverage is 100% and both parameters are fully documented there, including the enum of HTTP methods and the path example. The description adds only a light restatement ('route parameters'), so the schema is doing the heavy lifting and the baseline of 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: shows what one Trainer Connect operation accepts, enumerating route parameters and per-field validation rules (required, type, allowed values). This clearly separates it from list_operations (which enumerates operations) and from api_read/api_write (which execute them).

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 when to use it — 'before api_write so the request is right the first time' — which names a sibling alternative and the condition selecting this tool. It stops short of stating when not to bother (e.g. trivial GETs), so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description corroborates the closed-world scope by calling it the public directory. It adds real context beyond the annotations: results are capped at 10, include a public profile link, and contact details are never returned because contact happens through the profile page. Pagination behavior beyond the cap is not explained.

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

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

Three sentences, each earning its place: scope and facets first, then the Portuguese-language caveat, then return-shape and privacy behavior. No filler and no repetition.

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

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

For a read-only, zero-required-parameter search tool with no output schema, the description covers what it searches, what comes back (up to 10 results with profile links), what is deliberately withheld (contact details), and the domain quirk (Portuguese specialties, mostly Brazil). Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the Portuguese-language guidance and the online/in-person enum. The description's Portuguese specialty examples and Brazil-centric framing largely restate what the schema provides, so it sits at the baseline rather than adding new semantic 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?

States a specific verb and resource (find personal trainers in the public Trainer Connect directory) plus the searchable facets (specialty, name, city/state, modality) and the geographic scope. An agent can distinguish it from the singular get_trainer sibling 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?

Clearly frames this as a directory search with the criteria that drive it, and gives one concrete routing hint (omit location for online coaching). It never explicitly names get_trainer as the alternative for fetching a single known trainer, so the when-not condition is left implicit.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds useful scope by specifying that only active diets are returned and that the start date is included, but it does not describe ordering, pagination, or response shape.

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

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

The description is a single front-loaded sentence with no wasted words. It communicates the core query and the key returned attribute efficiently.

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 zero-parameter read tool, the description is mostly complete: it tells the agent it returns students with active diet plans and since when. It could be stronger by mentioning response organization or ordering, but the annotations and lack of parameters keep the remaining burden low.

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 has zero parameters, so there is no parameter semantics for the description to clarify. The baseline for a parameterless tool is 4.

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 retrieval target: students with an active diet plan and the date since when it has been active. It is clear enough to distinguish from generic diet-plan listing tools, but it does not explicitly name how it differs from siblings such as list_diet_plans or get_diet_plan.

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

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

There is no explicit when-to-use guidance, no alternatives, and no exclusions. The word active implies a current-state query, but an agent must infer when to choose this over list_diet_plans, get_diet_plan, or get_diet_adherence.

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 'Read only' merely repeats structured data. It adds nothing about return cadence, whether values are live or cached, what happens at zero credits, or what the payload contains — the useful behavioral context is absent.

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

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

Two short sentences with the resource stated first. The trailing 'Read only' is redundant with the annotations and earns no place, but otherwise there is no padding.

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

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

For a zero-param, no-output-schema tool the description must at least imply the shape of the answer. It says credits exist for three categories but not whether the result is a single total, a per-category breakdown, or a balance object, and it does not resolve overlap with the three sibling quota/statement tools.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 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 resource (remaining AI credits) and scopes it to the three generation categories (workout, diet, assessment). However, it does not distinguish itself from near-identical siblings such as get_ai_credits_statement, get_assessment_ai_quota, and get_workout_ai_quota, leaving an agent guessing which of the four to 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?

No when-to-use guidance and no exclusions. Given three sibling tools about AI quota/credits, the description should say when this current-balance tool is preferred over the statement or the per-domain quota tools, but it is silent.

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 'Read only' in the description is a pure restatement rather than added context. Nothing is said about what a statement contains (rows, date range, pagination, totals) even though there is no output schema to cover that.

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?

At two short sentences it is certainly compact, but the first sentence is not well-formed English and the second is redundant with annotations, so the brevity comes at the cost of clarity rather than from tight writing.

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?

Because there are no parameters and no output schema, the risk of a wrong invocation is low, but the description leaves the agent unable to tell what comes back or how this differs from get_ai_credits. A single clause on scope (e.g. 'itemized history of credit consumption, newest first') would close the gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. It does not claim any filtering capability that would need explaining.

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 gestures at the resource (AI credit usage/additions, i.e. a credit ledger) but the phrasing 'What used and added AI credits' is grammatically broken and never names a verb. It does not distinguish this statement/history view from the nearby get_ai_credits, get_balance, or get_statement siblings, so an agent must guess which one returns the history.

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

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

There is no when-to-use guidance, no mention of the alternative get_ai_credits (likely current balance/quota), and no indication of the period covered. The only signal is the title phrase 'credits history', which the agent has to interpret on its own.

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 only a marginal hint that the payload is the form's questions rather than answers or metadata, which is a small contribution for a tool with no output schema to explain the response.

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

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

It is certainly short and has no wasted words, but it is an incomplete sentence rather than a front-loaded explanation. Conciseness here shades into under-specification rather than economy.

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

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

For a simple read tool with full schema coverage and annotations, an agent still cannot tell whether the response contains question text, options, ordering, or the student's answers (which have a separate sibling). With no output schema, the description needed to state what comes back, and it does not.

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% with a single integer formId whose schema text already points to list_anamnesis_forms as the id source. The description adds no further semantics, so the baseline 3 for fully documented parameters 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 questions of one anamnesis form" is a noun fragment with no verb; only the title ("See an anamnesis form") supplies the retrieval intent. It does hint at scope (questions of a single form) but doesn't clearly separate it from siblings like list_anamnesis_forms or list_anamnesis_answers.

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

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

There is no statement of when to use this tool, no prerequisites, and no mention of when to use list_anamnesis_forms or list_anamnesis_answers instead. The only routing hint sits in the parameter schema ("Id from list_anamnesis_forms"), not in the description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing that output is one row per student and that the set is filtered to pending-or-answered anamneses, though it says nothing about ordering, volume, or what fields each line contains.

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 eleven-word sentence with no filler, and the key scoping fact (pending or answered) sits at the end where it is easy to catch. It is efficient, though it reads as a fragment rather than a front-loaded statement of purpose.

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

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

For a no-parameter read tool with no output schema, the description carries the burden of explaining the return value, and it only partially does so: it never says what a "line" comprises (student identity, status, dates). Adequate to call it, but incomplete for interpreting 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, so the baseline of 4 applies; there is nothing the description needs to disambiguate. The implicit filtering to pending-or-answered is worth noting but does not correspond to a parameter.

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

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

The sentence describes the result shape ("one line per student") and the scope (anamnesis pending or answered), which conveys that this is a status overview. But the action verb is only implied by the tool name, and it never distinguishes itself from nearby siblings like list_anamnesis_answers or list_anamnesis_forms.

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

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

There is no explicit when-to-use guidance and no mention of alternatives, even though list_anamnesis_answers and list_anamnesis_forms are obvious candidates for related questions. The agent must infer that this is the aggregate view while those are the detailed views.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds that the actual anticipation operation happens in the app, which is useful beyond the annotations, but otherwise repeats the read-only nature and gives no permission, rate-limit, or response-shape details.

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 short and front-loads the core purpose (receivable anticipation limit and fee). The second sentence clarifies read-only scope and where the action lives, with no wasted text.

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

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

For a zero-parameter, no-output-schema read operation, the description covers what is returned (available anticipation amount and fee) and clarifies that it does not perform the anticipation. It could specify scope (e.g., per account or per student) but is otherwise adequate.

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 has zero parameters, so there are no parameter semantics to explain. The description does not need to compensate for schema gaps, and the baseline for zero-parameter tools applies.

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

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

The description states a specific resource (future receivables anticipation limit) and what is returned (how much can be anticipated now and the fee). It implicitly distinguishes from an action tool by noting that anticipating itself happens in the app, though it does not explicitly name sibling tools like list_anticipations.

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 phrase 'Read only: anticipating is in the app' signals that this is a read-only check and not an action tool, which gives some usage context. However, it does not explicitly say when to use this versus alternatives such as list_anticipations or get_receiving_status, leaving selection to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered externally. The description adds genuine value by disclosing the payload ('every measurement and the photos'), but nothing about photo format (URLs vs. binary) or size of the response.

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

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

One short clause with zero filler, and the distinguishing element (a single assessment with all measurements) is front-loaded. It is a fragment rather than a sentence, which costs nothing in a tool description.

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

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

For a single-parameter read with no output schema, the description is minimally adequate: it tells the agent it will receive measurements and photos. It does not explain the response shape or what happens when the id is unknown, which is the main remaining gap given the absence of an output 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% and the single assessmentId parameter is documented with its source ('The id from list_assessments'). The description adds no additional meaning about the identifier, 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 resource ('One physical assessment') plus what comes back ('every measurement and the photos'), which clearly separates it from the list_* siblings. The retrieval verb is implied rather than stated, but no agent could read this as anything other than a single-record fetch.

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

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

There is no when-to-use guidance and no named alternative such as list_assessments or get_latest_assessments; the only routing hint lives in the schema ('The id from list_assessments'), not the description.

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

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

The description discloses a crucial behavioral constraint: 'if there is one.' This informs the agent that the tool may return no data if no analysis has been written for the assessment, which is valuable context not provided by the readOnly/destructive hints 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?

The description is extremely brief and front-loaded, capturing the core function and the essential edge case (existence) in a highly concise manner without any 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?

Given the simplicity of the input (1 parameter) and the high clarity of the purpose, the description is functionally complete for triggering the tool. It only lacks detail on the format of the analysis, which would typically be found in an output 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?

Since schema description coverage is 100%, the parameters are well-documented by the schema itself. The description does not add specific meaning or nuance to the 'assessmentId' beyond confirming it refers to the ID of a specific assessment.

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 defines the function (retrieving AI analysis) and the target object (an assessment). While the name is highly specific, the description adds a layer of intent by specifying the 'AI analysis' aspect, making it clear what kind of data is returned compared to general assessment 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?

The definition offers almost no usage guidelines. It does not tell the agent when to choose this tool over general tools like 'get_assessment' or when the analysis is actually expected to exist, leaving the agent to rely solely on execution and error handling.

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 'Read only.' merely repeats structured data and earns no credit. The only added signal is that the quota belongs to 'the trainer' (caller-scoped), with no mention of units, reset periods, or whether the count is shared across students.

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

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

Two short sentences with the core quantity front-loaded and no padding. The trailing 'Read only.' is redundant against the annotations, costing a small amount.

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?

A zero-param read tool is inherently simple, but there is no output schema, so the description ideally would describe the returned shape (remaining count alone vs. limit/used/remaining). As written, an agent knows what it asks for but not what it gets back.

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

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

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate at the parameter level. The description stays consistent with the empty schema.

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

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

States a specific resource (AI assessment analyses) and the exact quantity returned (how many the trainer has left), so the verb+resource intent is clear. It fails to differentiate from close siblings such as get_workout_ai_quota and get_ai_credits, which an agent could easily confuse with this one.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. With three nearby quota/credit tools in the sibling list, the agent is left to infer that this one is assessment-specific purely from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful distinction that the payload mixes completed actions ('did') with pending proposals ('suggests'), which matters for how the agent interprets results. It says nothing about volume, pagination, or timeframe, but with annotations present the bar is lower.

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

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

A single front-loaded sentence with no filler. It is arguably too compressed rather than bloated — the 'did or suggests' ambiguity and lack of usage routing are gaps in content, not verbosity.

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

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

For a zero-parameter read tool this is close to sufficient, but with no output schema the description should indicate the shape of what comes back (list of items? counts? both actions and suggestions in one array?) and whether it is scoped to the calling trainer. Those details are left unresolved.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description's parenthetical examples are the only qualifiers available and they are used adequately.

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

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

The description names the resource (the app's autopilot actions) and clarifies with concrete examples (reminders, follow-ups) plus the scope 'for the trainer'. The verb is implicit in the tool name rather than stated, but 'what the app's autopilot did or suggests' is specific enough to distinguish it from the many get_* list/detail tools around students, workouts, and diet plans.

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

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

There is no guidance on when to call this versus other summary tools such as get_student_notices or list_notifications, which could plausibly surface similar automated reminders. No preconditions, no exclusions, and no alternatives are mentioned; the agent must infer usage entirely from the tool name.

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