GymFlexa Gym Management

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

Annotations already declare the mutation side (readOnlyHint=false, destructiveHint=true) and idempotency, so the description's added value is in disclosing that gym defaults for session length and reminders are applied and that reminder messages will go to the member — a real consequence the agent can relay. It still doesn't cover failure behavior such as a slot already being taken 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?

Three short sentences, front-loaded with the usage trigger, then the return value, then the default/reminder side effect, then the exclusion. Every clause does work and nothing is redundant.

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

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

With an output schema present, return values need not be spelled out, and the description still summarizes them; combined with the defaults and idempotency context this covers most of what an agent needs for an 8-parameter mutation. Gaps remain around conflict/failure handling, which matters given destructiveHint=true.

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 parameters are well documented (including requestId idempotency and the gymId/providerIds omission rules), so the schema carries the load and a 3 is the baseline. The description only echoes the durationMinutes default and adds the reminder implication, not new per-parameter meaning.

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

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

The description pairs a specific verb ("book") with a precise resource ("a member into a session, class or personal training at their gym") and immediately frames itself as the booking action, distinct from cancel, reschedule, and availability siblings. An agent can route requests correctly 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 gives an explicit trigger ("when someone asks to book a member into a session") and one explicit exclusion ("Not for finding free slots"), which cleanly routes slot-discovery to get_gym_availability. It does not name reschedule_appointment or cancel_appointment as the alternatives for existing bookings, leaving that inference to the agent.

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, idempotentHint and readOnlyHint=false, so the safety profile is covered; the description still adds a meaningful non-obvious detail: the session is soft-cancelled, "kept rather than deleted," and the response indicates whether the gym's cancellation message is sent to the member. It does not restate annotation facts, and it does not contradict the destructive hint since the state change is still irreversible.

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

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

Three short sentences with the trigger condition front-loaded and no filler. The middle sentence is slightly convoluted in phrasing ("Returns the session as canceled, kept rather than deleted, and whether...") but still parses.

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

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

For a 2-parameter mutation with full schema coverage, rich annotations and an output schema, the description supplies what structured fields cannot: the soft-delete semantics and the decline-request variant. Only minor gaps remain, such as permissions or the stale-write refusal, which the schema already covers.

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 carry their own descriptions (appointmentId sourced from list_appointments, expectedLastEditTime as an optimistic-concurrency guard). The description adds no parameter-level syntax or sourcing beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource (cancel a member's session) and covers the dual case of declining a member-requested session, which an agent could not infer from the name alone. It explicitly carves out the reschedule case, so it is distinguishable from reschedule_appointment 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?

Gives a clear trigger condition ("when someone asks to cancel... or decline one the member requested") plus an explicit exclusion ("Not for moving a session to another time"). It stops short of naming reschedule_appointment as the alternative, leaving the agent to map the exclusion to the sibling.

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

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

The annotations already declare readOnly=false, idempotent=true, destructive=true, and openWorld=false. The description adds useful context that phone and email are saved but never returned, and it scopes out updates. However, it does not explain the destructiveHint implication or expand on idempotency beyond what the requestId schema already says.

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 three short sentences and is front-loaded with the trigger condition. Each sentence contributes distinct information: usage, return/privacy behavior, and exclusion. There is no filler.

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

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

For a simple create tool with rich schema descriptions, annotations, and an output schema, the description covers the trigger, exclusion, and sensitive return behavior. It leaves the destructive annotation unaddressed, but the schema and annotations already carry most operational details.

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

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

Schema description coverage is 100%, and the schema fully documents all six parameters, including requestId idempotency and gymId default behavior. The description adds no parameter-level meaning beyond noting that phone and email are stored but omitted from the response, so the baseline 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: 'add a new member to a gym.' It also distinguishes itself from the update workflow with 'Not for changing an existing member,' so an agent can identify the tool 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 gives an explicit trigger: 'Use this when someone asks to add a new member to a gym.' It also provides a clear exclusion for changing an existing member, though it does not name update_member directly or discuss duplicate handling beyond the schema's requestId field.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description adds genuinely new behavioral detail: return cardinality and ordering (up to 14 rows, Monday first) and error semantics (id outside the organization returns not-found).

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

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

Three short sentences, each earning its place: trigger and scope first, then return shape, then error behavior. No redundancy or filler.

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

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

An output schema exists, so return values need not be explained, and the description still adds ordering, row cap, and not-found behavior. For a single-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single gymId parameter is fully documented with format and source ('as the gym list returns it'). The description adds nothing about the parameter, 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?

Names a specific verb+resource (get one gym's setting) and enumerates exactly what it returns: opening hours, timezone, currency, default session length. This is concrete enough to distinguish it from summary-style siblings like get_gym_schedule_summary.

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 clear trigger ('when someone asks for one gym's opening hours...') and one explicit exclusion ('Not for free session slots'), which routes the agent toward get_gym_availability. It stops short of naming that sibling explicitly, so it is contextually clear but not fully exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context the annotations don't: it discloses the return shape (per-day open-slot count plus first start/last end time), the 14-day window, that skipped days mean no availability, and that names are omitted.

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

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

Front-loaded with the use-case trigger and dense but purposeful. The second sentence is somewhat run-on in packing return shape, window, and exclusions together, but no sentence is wasted.

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

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

For a single-parameter read-only tool with an output schema and full annotation coverage, the description supplies everything an agent needs: when to use, what is returned, the time window, and the booking exclusion. Nothing material is missing.

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

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

Schema coverage is 100% and the single gymId parameter is fully documented in the schema, so the description adds no parameter-level detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('find free session slots') and scopes it to gym availability. It is clearly distinguishable from siblings like get_gym_schedule_summary by emphasizing openings/booked days rather than a schedule, and the closing 'Not for booking a session' removes ambiguity.

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

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

Opens with an explicit when-to-use trigger ('when someone asks when their gym has free slots... or which coming days are fully booked') and states a when-not ('Not for booking a session'). It does not name a specific alternative sibling tool, but the usage context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: totals include every status, coverage is capped at 31 days and 100 payments, and the default 7-day-ahead window holds no payments yet — a real trap for callers. It stops short of mentioning auth or rate-limit behavior, so a 4 rather than a 5.

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

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

Three tightly packed sentences, front-loaded with the trigger, then the return shape, then the limits, then the exclusion. No filler and no repetition of the tool name or 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?

An output schema exists, so return values need no explanation here. The description supplies the trigger, the scope of aggregation, the size/time limits and the 'cannot move money' boundary — everything an agent needs to select and call this correctly against its siblings.

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 gymId, startTime and endTime are already fully documented in the schema, including their defaults and the 31-day maximum. The description only echoes the default window and the start/end relationship, adding no syntax or format detail beyond what the schema provides. Baseline 3 applies.

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

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

The description states a specific verb and resource ('summarize how much their gym took in') and enumerates the dimensions summarized: counts by payment status and totals by currency. It is clearly distinguishable from the sibling tools, which cover gym metadata, availability, schedules and services rather than payments.

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 leads with an explicit trigger ('Use this when someone asks how much their gym took in...') and closes with an explicit exclusion ('Not for moving money: it cannot charge, refund or transfer'). Both the when-to-use and when-not-to-use conditions are stated rather than 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 readOnly/idempotent/non-destructive, so the description is free to add behavior they cannot express: counting includes all booking statuses, the window is capped at 31 days, the default window is the next 7 days, and counting stops at 100. The result cap and default window in particular are operationally important and appear nowhere 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?

Three sentences, trigger condition front-loaded first, followed by scope/limits and then negative scope. Every clause carries information (window limit, default, cap, exclusions) with no filler.

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

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

An output schema exists, so return-shape explanation is unnecessary; the description instead supplies the behavioral facts an output schema cannot (per-UTC-day aggregation, status-agnostic counting, 100-count cap, 31-day window). 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%, and the schema already documents startTime/endTime defaults and the 31-day constraint, so the description contributes no additional parameter detail beyond what the agent will read anyway. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description pairs a concrete verb and resource ('Returns booking counts per UTC day for one gym') and constrains the scope ('whatever their status', 'any window of at most 31 days'). Combined with the title, an agent can distinguish this from get_gym_availability or get_gym_payment_summary without opening any schema.

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

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

It gives an explicit trigger ('when someone asks how busy their gym is or how many appointments or sessions are booked each day, past or upcoming') and explicit exclusions ('Not for counting cancellations or seeing which members are booked'). It stops short of naming which sibling to use instead for those cases, so it is clear context without full alternative routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: results span all the user's gyms unless scoped, are ordered latest first, are capped at 100, and carry status and edit time. It does not mention whether a cursor or offset exists for going beyond the limit, which is the main remaining unknown.

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 selection criteria an agent needs before deciding to call, then the return shape. Dense but every clause maps to a decision or expectation. The phrase 'including to move or cancel one' is slightly compressed and takes a moment to parse.

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?

Five optional filters, no required parameters, an output schema, and full annotation coverage mean the description only needs to convey scope, ordering, cap and boundaries, all of which it does. The one gap is behavior at the limit (truncation vs. paging), which matters for a list tool that caps at 100.

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%, including id provenance for gymId and memberId and ISO 8601 formats, so the schema already carries parameter meaning. The description only reinforces the date-window and gym-scoping concepts and the 100 cap; it adds no semantics 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 resource (listing booked gym sessions) and enumerates the concrete question shapes it answers: when a member is booked, which sessions a trainer has, what is booked on a day. It also carves out a boundary against the busier-day counting case, which separates it from get_gym_schedule_summary and get_gym_availability.

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 opening clause gives explicit triggering conditions, and the closing sentence gives an explicit when-not ('Not for counting how busy each day is'). It also hints at the follow-on flow ('including to move or cancel one'), i.e. fetch the id before reschedule_appointment or cancel_appointment. It stops short of naming the alternative tool to use for the excluded case, so it is not a full routing statement.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuine beyond-annotation behavior: alphabetical ordering, a default page size of 25, and pagination via the returned cursor. It does not restate the read-only nature.

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: usage trigger front-loaded, then return/pagination facts, then a one-clause exclusion. No filler and nothing out of order.

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

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

An output schema exists, yet the description still supplies ordering and default page size, plus the when-to-use trigger and the member-search exclusion. An agent has everything needed to select and 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%, so limit and cursor are already fully documented with defaults and maximums. The description's '25 per page by default' repeats the schema, and only the alphabetical-sort detail adds anything, so the baseline 3 is warranted.

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 ('which gyms or studios they run') and enumerates the returned fields (id, name, currency, default language, last edit time). It explicitly distinguishes itself from the single-gym siblings by noting it is 'not for finding a member' and by returning a list rather than an overview.

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

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

Gives a clear trigger ('when someone asks which gyms or studios they run... or a gym's id is needed') and one explicit exclusion ('Not for finding a member'). It does not name the sibling to use for a single gym's details (get_gym), so routing to alternatives is implied rather than spelled out.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is fully covered. The description adds the shape of a result row (unit, quantity, minimum, low-stock flag) and the 100-item ceiling, but the output schema already defines the return shape and the schema already caps limit at 100. What remains undisclosed is whether the list is paginated beyond the limit or how ordering works.

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

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

Three short sentences with zero padding: the when-to-use cue comes first, the return summary second, and the exclusion last. Nothing 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 read-only list tool with an output schema and fully described parameters, the description covers the trigger, the result contents, and the size ceiling. The small residual gaps are pagination behavior and ordering, which are minor given that the output schema carries the return contract.

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%: gymId, limit, search, and lowStockOnly are each documented in the schema, and the description adds no format, default, or edge-case guidance beyond what is there. The mentions of the low-stock flag and the 100-item cap restate schema content rather than extend it, so the baseline 3 applies.

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

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

The description states a specific verb and resource: it lists stock items and their remaining quantities for a gym, and explicitly carves out retail prices as out of scope. It is clear what the tool does, though the only differentiation offered is against pricing rather than against a named sibling such as set_inventory_quantity.

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?

"Use this when someone asks how much of a product or supply is left in the gym's stock or what is running low" gives a concrete triggering question type, and "Not for retail prices" sets a boundary. It stops short of naming the alternative tool for changing quantities, so the agent must infer that writes belong elsewhere.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the default page size of 20, the 100 cap, cross-gym aggregation by default, and the fields returned. It stops short of saying what happens when the cap is hit (truncation vs. pagination), which matters for a capped list.

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

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

Three front-loaded sentences of trigger, behavior and exclusion, with no filler. The parenthetical '(20 by default)' sits well next to the cap, though sentence two crams default size, scope, return fields and optional filtering into one long clause that could be split for scanability.

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

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

Output schema exists, so return values needn't be explained, and the description nonetheless names the key fields. For a read-only capped list tool, what's missing is only the truncation/pagination behavior at the 100 limit and how to page past it — a modest gap rather than a blocker.

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 reinforces limit semantics ('up to 100 members (20 by default)') and the name-match behavior of search ('only those whose name matches'), which is a slight gloss over the schema's contains-words-in-any-order, accent-insensitive rule. It doesn't mention gymId scoping explicitly beyond 'across all the user's gyms or one'.

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

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

States a specific verb+resource (list members) with scope (all the user's gyms or one) and the returned fields (id, name, gym, last edit time). It also explicitly distinguishes itself from a sibling-style capability by excluding email, phone and notes, so an agent can tell it apart from member-detail lookups.

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?

Opens with an explicit trigger ('Use this when someone asks who their members are, or needs a member's id to book them, update their details or look up their sessions'), naming the downstream tools (book_appointment, update_member, session listing) that require an id from here. It also states a clear exclusion: not for email, phone or notes.

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

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

Annotations already declare readOnly, idempotent, non-open-world and non-destructive, so the safety profile is covered. The description adds useful behavior beyond that: results are scoped to exactly one gym, ordered alphabetically, and paginated at 25 by default. It doesn't discuss error behavior for an invalid or unauthorized gymId, which is the main remaining gap.

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

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

Three sentences, front-loaded with the use case, then the return shape and paging, then the exclusion. No filler and 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?

For a read-only, three-parameter listing tool with full schema coverage and an output schema, the description supplies everything an agent needs to select and invoke it: trigger, scope, ordering, and page size. Return-field documentation is correctly left to the 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 coverage is 100%, including the 24-hex format for gymId and the 25 default / 100 max for limit, so the schema already carries the parameter detail. The description's 'one gym' and '25 per page by default' restate schema facts rather than adding new semantics; only the alphabetical ordering is genuinely new, and that concerns output. 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 ('look up' / returns) plus resource (catalog services: classes, personal training, other services) and the fields returned. The closing sentence explicitly separates it from member purchase/attendance data, so it is distinguishable from list_members, list_appointments and the purchase-oriented siblings without opening their schemas.

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 opening clause gives the exact triggering condition (user asking what their gym charges, or needing a service id to book), and the final sentence gives an explicit exclusion ('Not for what a particular member bought or attended'). Both when-to-use and when-not are present; a named alternative tool would be a bonus but none of the siblings covers the excluded case directly.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds real behavioral context beyond them: result cap of 100, organization scoping, and the single-person-gym edge case. It stops short of saying what happens when the cap is exceeded or how paging works, which keeps it below a 5.

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

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

Three short sentences, front-loaded with the usage trigger before the return shape, then the exclusion last. Every sentence carries distinct information with no repetition of 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?

An output schema exists, so the description need not explain return values, and it still usefully flags the 100-item cap and org scope. The only material gap is behavior at the cap boundary, which an agent might need to know for large organizations.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline for a no-param tool applies. No misleading parameter language is introduced.

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

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

States a specific verb and resource (list trainers who take sessions) and immediately distinguishes itself from neighboring concerns by naming what it is not: trainers' working hours. An agent can tell this apart from get_gym_availability or list_members without opening a schema.

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

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

Gives explicit trigger conditions ('when someone asks which trainers can be booked') and the downstream purpose (obtaining a trainer id to book a member or to find their sessions), plus an explicit exclusion. Nothing is left to inference about when to call it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds real context beyond that: the returned object, that member/trainer/services stay fixed, and that reminders follow the session. It does not explain why the call is flagged destructive (e.g. the old slot being released or overwritten), which leaves a gap worth one point.

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 plus a short exclusion, with the triggering condition front-loaded and every clause carrying information about usage or preserved state. Nothing is redundant with 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?

An output schema exists, so return shape need not be spelled out, yet the description still summarises what comes back and what is preserved. It is missing only edge behaviour an agent might need, such as what happens when the new time conflicts with the member's or trainer's existing bookings.

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

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

Schema description coverage is 100%, so all four parameters, including the expectedLastEditTime concurrency guard, are already documented in the schema; baseline 3 applies. Worse, the phrase 'its ... length stay[s] the same' sits slightly at odds with the optional durationMinutes parameter that changes the length, so the description adds no parameter clarity and a little 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?

Specific verb and resource: 'move a member's session to another day or time', matching the name and title. It also rules out the nearest sibling with 'Not for cancelling a session', so an agent can separate this from cancel_appointment/book_appointment without opening a schema.

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

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

Gives a clear triggering condition ('when someone asks to move a member's session') and one explicit exclusion (cancelling). It does not address the neighbouring case of booking a brand-new session instead of moving an existing one, so the routing guidance is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is largely covered. The description still adds real value beyond that: it discloses the return shape (previous and new quantity) and states the set-versus-adjust semantics ('the number given replaces the stored one'), which prevents a common off-by-delta error. The stale-edit refusal behavior exists but is only documented in the schema field, not here.

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

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

Three short sentences with the use condition front-loaded, then the result, then the exclusion — no filler, no restatement of the tool name.

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

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

An output schema exists, so return-value explanation is not strictly required, and the description nonetheless covers the outcome. For a destructive mutation it is nearly complete; the only omission is that a mismatched expectedLastEditTime causes a refusal, which an agent must read from the schema field rather than the description.

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

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

Schema description coverage is 100%, so all three parameters (including the optimistic-concurrency expectedLastEditTime) are already documented at the field level. The description echoes the replace semantics of `quantity` but adds no format, unit, or reconciliation guidance beyond the schema. 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 names a specific operation on a specific resource ('correct or update how much of a stock item the gym has') and adds an explicit negative boundary ('Not for adding a new stock item'), which separates it from creation flows. Combined with the name and title, an agent can tell exactly what this does 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 gives a clear trigger condition ('when someone asks to correct or update') and an exclusion ('Not for adding a new stock item'). It stops short of naming the sibling/alternative to use for the excluded case (e.g., a create-inventory tool or list_inventory_items, which is only referenced inside the schema), so the routing is clear but not fully closed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuine behavioral context beyond them: the exact transparency boundaries (no member, trainer or payment data) and the windowing limits (7 days of booking counts, 14 days of slots, 12 services with prices). It says nothing about permissions or result caps beyond those limits, but this is solid added value.

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

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

Three sentences, front-loaded with the selection trigger, then the payload description, then the exclusion. Dense but every clause carries either scope or content information; only the long enumerations push it toward terseness fatigue.

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 an output schema exists, the description need not explain return values, yet its summary of the card's contents and the explicit data exclusions make the tool's boundaries unambiguous. For a one-parameter read tool with full annotations, nothing essential 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?

The single gymId parameter is fully documented in the schema (format pattern, source of the value), and the description adds no further syntax or sourcing guidance. With 100% schema coverage, the schema carries this dimension and the description correctly stays out of the way.

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 ('quick overview or dashboard of one gym') and enumerates what the overview card contains, which sets it apart from narrower siblings like get_gym_availability. However, it never names the overlapping gym siblings (get_gym, get_gym_availability, list_gyms) it should be chosen over, so the differentiation is by content rather than by explicit contrast.

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

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

Gives a clear trigger ('use this when someone wants a quick overview or dashboard of one gym') and an explicit exclusion ('Not for a single member or booking'). It stops short of naming the alternative tool to call for those excluded cases, so routing for sibling gym tools is left to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the return payload scope and a useful privacy guarantee ('contact details are never returned'), but it never explains what makes this destructive (e.g. whether omitted fields are left untouched or wiped) or what happens on a stale expectedLastEditTime beyond the schema's own note.

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 tight sentences: trigger, return shape, exclusion, each earning its place with no filler. The return-value sentence overlaps the output schema slightly but also carries the non-obvious privacy statement, so it is not pure waste.

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

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

With an output schema present the return summary is a bonus rather than a necessity, and the annotations cover safety. The one real gap is partial-update semantics — whether fields not supplied are preserved — which matters for a destructive-flagged mutation but is absent from both description and schema.

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

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

Schema description coverage is 100%, so all six parameters are documented in the schema itself. The description only restates the set of editable fields and adds no format or constraint detail beyond that, which is the correct baseline when the schema does the heavy lifting.

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

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

The description opens with a specific verb plus resource ('change a member's name, phone, email or language') and enumerates the mutable fields, so an agent immediately knows what the tool does. It also explicitly separates itself from the create path with 'Not for adding a new member,' which disambiguates it from the create_member sibling.

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

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

It gives a clear trigger condition ('Use this when someone asks to change...') and one explicit exclusion (adding a new member). It stops short of naming create_member as the alternative or noting the prerequisite that memberId and expectedLastEditTime must first come from list_members, though the schema descriptions cover that.

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