Trainzilla Coach MCP

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses two traits — that notes are timestamped and that the operation is confirm-gated — but says nothing about permissions required, persistence/reversibility, or what the preview-only path yields (the schema covers the latter).

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 core action first and the qualifier and example appended. Zero filler; every clause adds 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 3-parameter mutation tool with no annotations and no output schema, the description covers the confirm gate, timestamping, and the use case reasonably. It is thin on permissions, side effects, and confirmation-flow behavior that an agent would otherwise need.

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 33% (only 'confirm' is documented), so the description should compensate. It clarifies the note's purpose via example and implies 'id' targets a prospect record, but adds no format or length constraints for the two undocumented required parameters.

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

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

The description gives a specific verb+resource ('Add a timestamped note to a prospect's record') and an illustrative example of note content, which goes beyond restating the name. It does not explicitly distinguish itself from siblings like update_prospect_status or create_prospect, though they don't overlap in function.

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 through the example ('e.g. what was discussed on a call'), which suggests the intended scenario. There is no explicit when-to-use/when-not guidance and no named alternative tool for related logging needs.

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

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

With no annotations, the description carries the full burden, and 'confirm-gated' does disclose the two-phase preview/execute behavior plus the move (overwrite) semantics. It says nothing about permissions required, what happens to a coach's prior location assignment, or side effects, so the disclosure is partial.

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, and the confirm-gating caveat is placed at the end where a reader will catch it. It is efficient, though terse given the tool's complexity.

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 annotations, no output schema, and 17% schema coverage, the description is too thin. It omits permissions, the meaning of makePrimary, and the effect on any existing assignment.

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

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

Schema coverage is only 17% (confirm is the lone documented parameter), so the description must compensate. It hints at role and the coach/location pair but leaves organizationId and especially makePrimary unexplained in both the description and 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 states a specific verb (assign or move) and resource (a coach to a location) with the organizational scope, so the agent knows this is an assignment operation. It does not, however, explicitly separate itself from near-neighbors like remove_coach_location_assignment or update_organization_coach_role.

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

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

There is no when-to-use or when-not-to-use guidance beyond the implied 'assign or move'. No alternatives are named, so the agent gets no routing help against the many role/coach-management siblings.

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?

No annotations are provided, so the description carries the full burden. It discloses that the operation is 'confirm-gated' (requires explicit confirmation to execute) and creates a habit per client, which is a mutation. However, it does not disclose other important behaviors like idempotency, error handling, or limits.

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, concise sentence that front-loads the purpose and key behavior. Every word earns its place with no fluff.

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 lack of annotations and output schema, the description covers the core action but misses details such as what the preview returns, error scenarios, or constraints. It is adequate but has clear gaps for an agent to use without further information.

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

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

Schema description coverage is only 33% (only the 'confirm' parameter has a description). The description does not add meaning for 'masterHabitId' or 'clientIds' beyond the vague phrase 'one or more clients'. It fails to compensate for the low schema 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 uses the specific verb 'Assign' and resource 'Master Habit', and clarifies that it creates a habit per client. This clearly distinguishes it from sibling tools like 'create_habit' (single habit creation) and 'create_master_habit' (master template creation).

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 a confirm-gated two-step process, which suggests when to use it (when assigning a master habit to multiple clients) but does not explicitly state when not to use it or mention alternatives.

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

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

With no annotations, the description carries the burden and does well: it discloses the confirm-gating, the permission requirement (owner/admin), and that omitting roleId clears the role. It does not describe reversibility, failure behavior, or return format, hence 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, front-loaded with the core action, then the authorization and caution. No filler; 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?

For a 4-param mutation with no annotations and no output schema, the description covers purpose, permissions, gating, and a caution to confirm targets. Return/result behavior is left implicit, but the essentials for correct invocation are present.

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 25% (only confirm is documented), so the description must compensate. It adds key semantics for roleId (omitting it clears the role), but says nothing about memberUserId or organizationId beyond their obvious names.

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 (assign/clear) and resource (custom role for a gym member), and explicitly covers both directions of the operation, including that omitting roleId clears the role. The word 'custom' distinguishes it from the sibling update_organization_coach_role.

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 the condition for use (owner or admin performing an access-control change) and a clear instruction to confirm which member and role first. It does not name alternative siblings or state explicit when-not conditions, but the 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?

The description aligns with the readOnlyHint annotation and adds behavioral context by detailing the output. It does not contradict annotations and provides transparency about what the tool returns.

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

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

The description is a single sentence that is concise and front-loaded. Every word contributes to understanding the tool's purpose and 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?

Given no parameters and no output schema, the description adequately covers the tool's function and return values. It lacks details on time range or statuses, but for a simple summary tool, it is reasonably 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 are no parameters, so the schema coverage is 100%. The description adds value by explaining the output format (minor units, currency, counts), which goes beyond 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?

The description clearly states the tool summarizes the coach's payments, specifying the output: total captured amount (in minor units), currency, and counts by status. It distinguishes itself from sibling tools like list_subscriptions which deal with subscriptions rather than payment summaries.

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 usage for retrieving a payment summary but does not explicitly guide when to use this tool versus alternatives. There is no mention of prerequisites or exclusions, but the no-parameter design makes it straightforward.

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; the description adds the formula name (Epley) and %1RM suggestions but no further behavioral traits. No contradiction.

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?

Single sentence, no wasted words, front-loaded with key 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 simple calculator with no output schema, the description explains the core function and formula. Could mention valid rep ranges or assumptions, but 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 0%, and the description does not explain the parameters. It only says 'from a working set', relying on parameter names (weightKg, reps) for 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 clearly states the verb 'estimate' and the resource '1-rep max (Epley) and %1RM weight suggestions', distinguishing it from sibling tools which focus on habits, billing, etc.

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

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

The description implies usage for estimating 1RM from a working set but provides no explicit guidance on when to use this tool versus alternatives or mention of 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=true, indicating no destructive side effects. The description adds the strategy-specific computation details but does not disclose any additional behavioral traits beyond what annotations cover.

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 concise with a single sentence followed by a clear breakdown of strategy ratios. It is front-loaded and efficient, though some might prefer a more structured format.

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 omits return value details. It covers the strategies but does not explain how parameters interact (e.g., that PRO uses proteinPerKg and fatPerKg). For a tool with 5 parameters and no schema descriptions, more completeness is needed.

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

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

Schema description coverage is 0%, so the description must compensate. It only explains the strategy parameter's enum values but does not describe the other parameters (calories, weightKg, proteinPerKg, fatPerKg) or their usage across strategies. Parameter names are self-explanatory, but the description adds minimal value.

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

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

The description clearly states the tool computes a macro split (protein/carbs/fat in grams) and lists the supported strategies with their ratios. This distinguishes it from sibling tools like calc_1rm and calc_tdee.

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 provides explicit ratios for each strategy (STANDARD, PRO, KETO), guiding the agent on which parameters to use. However, it does not explicitly state when to use this tool versus alternatives or provide context for when not to use it.

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

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

readOnlyHint=true already establishes this as a safe, non-mutating calculation, so the safety burden is covered. The description adds nothing about the underlying formula (e.g., whether bodyFatPct switches to Katch-McArdle), how defaults are applied, or that results are derived rather than stored.

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 that front-loads the computation and lists the outputs in order of derivation. No filler, though it is arguably too terse given the undocumented parameters.

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 does at least name what is returned, which is the minimum. But for a 7-parameter calculation with 0% schema coverage, it omits how the optional activity, goal, and bodyFatPct inputs shape the result.

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

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

Schema description coverage is 0% across 7 parameters, so the description carries the full explanatory burden and provides none of it. It never mentions gender, activity level, goal, or bodyFatPct, nor how activity/goal modify the recommended-calorie output.

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 (compute) and the concrete outputs (BMR, TDEE, recommended daily calories) plus the input source (client stats). It is distinguishable from calc_1rm and calc_macros by output, 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 guidance, no prerequisites, and no indication of when to pick this over calc_macros (which likely consumes the same calorie outputs). The agent must infer the workflow placement 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?

With no annotations, the description carries the full burden. It usefully discloses that the operation is confirm-gated (preview when confirm=false) and that booked members are affected, which is genuine consequence information. It does not state permissions required, whether cancellation is reversible, or whether members are 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?

Two tight sentences with no filler, and the confirm-gating constraint is front-loaded ahead of the member-impact warning. Efficient for the information it delivers.

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 destructive mutation with no annotations and no output schema, the description covers the gating and the member impact but leaves out permissions, reversibility, and the outcome for booked members beyond 'affected'.

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

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

Schema coverage is only 33%, with just the confirm parameter documented. The description hints that identifying the correct session matters ('confirm which session first') but adds no format or meaning for sessionId or reason, so it fails to compensate for the undocumented parameters.

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

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

States a specific verb+resource: 'Cancel one dated class session', and the word 'session' (vs. sibling cancel_gym_class / deactivate_gym_class) signals a scoped, dated instance rather than the whole class. It does not explicitly name those siblings, so differentiation is implied 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-gated' and 'confirm which session first' give some usage-relevant context about the two-step flow, but there is no explicit guidance on when to use this versus cancel_session, deactivate_gym_class, or reschedule_session.

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

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

With no annotations, the description carries the full burden. It does disclose two valuable traits: the operation is confirm-gated and the reason is client-visible. It omits whether cancellation is reversible, what happens to session attendees/notifications, and permission requirements, leaving meaningful behavioral gaps.

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 the core action and the confirm-gate front-loaded; every clause earns its place 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?

For a mutation tool with no annotations and no output schema, the description covers the confirm-gate and reason visibility but omits side effects, reversibility, and permissions. Adequate but with clear gaps an agent would want filled.

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

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

Schema coverage is only 33%, so the schema alone does not document 'reason' or 'sessionId'. The description partially compensates by clarifying that 'reason' is optional, short, and shown to the client. 'sessionId' remains undocumented and the confirm-gating is already explained in the schema.

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

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

States a specific verb+resource ('Cancel a scheduled session'), which is clear and distinct in intent. However, it does not differentiate itself from nearby siblings such as cancel_gym_class_session or reschedule_session, so an agent must infer which cancellation path applies.

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

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

The '(confirm-gated)' note implies a two-step usage pattern, which is useful context. But it never states when to use this instead of reschedule_session or cancel_gym_class_session, and gives no exclusions or 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?

With no annotations, the description carries the full burden and does so richly: owner-only auth, high-impact mutation, the specific side effects (unlisting, releasing coaches), the subscriber precondition, and the confirm-gated preview-vs-execute behavior.

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

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

Two dense sentences, front-loaded with the action and impact, then the precondition and confirmation requirement. No wasted 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?

For a high-impact mutation with no annotations or output schema, the description covers effects, auth, prerequisites, and the confirmation gate well. It stops short of stating irreversibility or what the response returns, a minor gap.

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

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

Schema coverage is 50% (only 'confirm' is documented). The description reinforces the confirm workflow and implies organizationId identifies the gym ('which gym'), but adds no format or constraint detail for organizationId, so it only partially compensates for the undocumented 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?

States a specific verb+resource ('Close a gym') and enumerates the concrete effects (unlists plans and public page, releases coaches), which clearly differentiates it from siblings like update_organization, delete_organization_location, or transfer_organization_ownership.

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 strong precondition ('Blocked while gym-plan subscribers are live') and the confirm workflow, making the when/when-not clear. It does not name a sibling alternative for the blocked case, so it falls just short of full routing 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?

With no annotations, the description carries full burden. It reveals the confirm-gated behavior (preview vs execution) but omits other important traits: that it creates a record, is irreversible, authentication needs, rate limits, or 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?

Two succinct sentences, front-loaded with key 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?

Given 4 parameters, nested objects, no output schema, and no annotations, the description is too thin. It does not cover return values, error handling, or behavior on conflicts, leaving the agent underinformed.

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 50%. The description adds value by explaining confirm-gating and listing question types, but does not explain clientId or the structure of questions beyond types.

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

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

The description clearly states it schedules a check-in for a client with optional questions, using a specific verb and resource. It distinguishes from siblings like list_checkins (listing) and schedule_session (session).

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 when to use (to schedule a check-in) but provides no explicit guidance on when not to use, alternatives, or prerequisites like client existence.

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

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

With no annotations, the description carries the full burden and does well: it discloses the confirm-gate preview behavior, idempotent re-run semantics for the same client/title, and a hard validation rule ('a meal with only calories/macros and no ingredients is rejected'). It stops short of stating authorization requirements or what the response returns, keeping 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?

Purpose and routing are front-loaded ahead of the detailed meal/ingredient guidance, so the hierarchy is sound. The ingredient example is verbose and the prose runs as a single dense block, but nearly every sentence carries actionable constraint information 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?

For a mutation tool with no annotations, no output schema, and 33% schema coverage, the description covers the critical gaps: confirmation flow, validation rejection, ingredient requirements, unit conventions, and idempotency. It is missing only permission/auth context and any indication of the return payload, which are secondary given there is no output schema to explain.

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

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

Schema coverage is only 33%, so the description must compensate, and it does: it expands on confirm, the meals array shape (name/scheduledTime/order/days/section/calories/macros/description/ingredients), the required ingredients breakdown with a concrete example, and the legacy slot auto-mapping. It adds real meaning beyond the terse schema, though a couple of fields (e.g. endDate, avatarUrl/recipeUrl) remain unexplained.

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

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

States a specific verb and resource ('Create a diet plan for a client') plus the confirm-gate qualifier, and explicitly distinguishes itself from the sibling list_diet_plans. An agent can tell exactly what this tool 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?

Explicitly names the alternative (list_diet_plans) and the condition that selects it ('is it done?'), and warns against calling this tool again to check status. It also documents the idempotency behavior for repeated confirm:true calls, leaving nothing to inference.

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

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

With no annotations, the description carries the full burden. It usefully discloses the confirm-gated preview/execute flow and the meal-level ingredients/quantities requirement, but omits permissions, visibility effects, and what the preview returns.

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

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

Two dense, front-loaded sentences with no filler — the core action leads and the meals constraint follows. Slightly terse given the parameter surface, but nothing is wasted.

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

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

For an 8-parameter mutation with no annotations, no output schema, and 13% schema coverage, the description is too thin. It never addresses most parameters or the visibility/permission implications of saving a shareable 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 13% across 8 params, so the description needs to compensate and largely does not. It adds meaning only for 'meals' (nested ingredients array with quantities) and implicitly for 'confirm'; goal, tags, difficulty, visibility, title, and description are left undocumented.

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

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

States a specific verb+resource ('Save a reusable diet plan template'), and the 'template' qualifier separates it from create_diet_plan. It does not explicitly name the sibling it differs from, so it is clear but not fully differentiated.

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

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

Only clue about when to use it is the parenthetical '(confirm-gated)', which describes mechanics rather than usage context. No guidance on when to prefer this over create_diet_plan or update_diet_plan_template, and no 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?

With no annotations, the description carries the full behavioral burden, and it only partially does so: it discloses that the call is a mutation gated by confirmation and that created sessions become bookable by members. It omits permissions/roles required, what happens on scheduling conflicts, timezone defaults, and idempotency. The confirm-gate detail is also duplicated in the schema, so its marginal value is limited.

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, mutation nature front-loaded, no filler or repetition. It is efficient, though the extreme brevity borders on under-specification rather than tight 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?

For an 11-parameter, 6-required mutation with no annotations and no output schema, the description omits auth requirements, the recurring-schedule model (how weekdays/startTime/timezone interact), and any parameter guidance. It is not complete enough for an agent to call this correctly without reading the schema carefully.

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 36% across 11 parameters, so the description is expected to compensate for undocumented fields (title, capacity, organizationId, durationMinutes, locationId, instructorCoachId) but explains none of them. It adds no syntax, format, or default information beyond what the schema already states.

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

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

States a specific verb and resource (create a recurring gym class) and adds a scope qualifier ('recurring') that separates it from one-off session creation. It does not, however, contrast itself with nearby siblings like update_gym_class or deactivate_gym_class, so the 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?

There is no when-to-use guidance, no prerequisites (e.g., an existing organization, location, or coach), and no named alternative for modifying or canceling an existing class. The only usage-adjacent signal is the parenthetical 'confirm-gated', which is not framed as a workflow instruction.

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

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

With no annotations provided, the description carries the full burden. It discloses the confirm-gated behavior (preview vs actual creation) and specifies format for daysOfWeek and reminderTime. However, it lacks details on permissions, destructive actions, or what happens on failure.

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 very concise, using two sentences that front-load the purpose and key parameter info. It is well-structured for quick reading, though could benefit from a bullet list for clarity with many parameters.

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 10 parameters and no output schema, the description should explain what the tool returns or prerequisites. It does not mention the response format (e.g., created habit object) or required client existence. Important context is missing for an agent to use it effectively.

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. It adds meaning for daysOfWeek (range and empty meaning) and reminderTime (format). But it leaves 7 other parameters (clientId, name, emoji, description, category, frequency, targetCount) without any explanation, which is insufficient given low schema 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 clearly states the tool creates a habit for a client and notes it is confirm-gated. However, it does not differentiate from sibling tools like create_master_habit or assign_master_habit, which reduces clarity about which tool to use.

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 explicit guidance on when to use this tool vs alternatives such as create_master_habit. The confirm-gated note hints at a preview mode but does not explain conditions for choosing this over other habit-related tools.

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?

No annotations provided, so description carries full burden. Only mentions 'confirm-gated' behavior, but lacks details on authentication, side effects, idempotency, or error conditions. Minimal behavioral disclosure.

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?

Single sentence, concise, and front-loaded with key purpose and behavioral hint. No wasted 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 7 parameters, no output schema, and 14% schema coverage, the description is insufficient. It does not explain return values, error handling, or differentiate Master Habit from regular habit. Lacks vital context.

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 14% (only confirm). The description adds no parameter-level detail, failing to compensate for the low coverage. Critical parameters like name, emoji, category lack explanation.

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

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

The description clearly states the tool creates a reusable Master Habit in the coach's library, distinguishing it from sibling tools like create_habit (likely for client habits) and assign_master_habit.

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 explicit guidance on when to use this tool versus alternatives (e.g., create_habit). The 'confirm-gated' hint is present but not elaborated. Usage context is implied but not fully clarified.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose two useful facts: the operation is confirm-gated and the creating coach becomes owner. However, it omits permission requirements, whether the org is immediately active, and any reversibility/cleanup semantics.

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 that carries the action, the gating mechanism, and the ownership outcome with zero filler. Nothing is redundant or 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?

For a mutation tool with no annotations and no output schema, the description covers purpose, confirm-gating, and ownership but leaves gaps around authorization requirements and post-creation state. Adequate but incomplete against the tool's mutation 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 50% — the 'confirm' param is documented in the schema (preview vs execute) and the description's 'confirm-gated' note reinforces it, while 'name' is undocumented but self-evident (required string, minLength 1). The description adds no name-format or naming-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?

States a specific verb+resource ('Create a new organization') and adds the consequential outcome that 'the coach becomes its owner'. The resource name distinguishes it from siblings like create_organization_custom_role and create_organization_location, though it does not explicitly contrast with 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?

No when-to-use, when-not-to-use, or alternative guidance is provided. It says nothing about prerequisites (e.g., what role or plan is required to create an org) or how it relates to invite/join flows in the sibling set.

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

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

With no annotations, the description carries the full burden and does disclose two important traits: the operation is confirm-gated (preview unless confirmed) and requires owner-level authorization. It omits reversibility, rate limits, and return behavior, but the two disclosed traits are the ones that most affect correct invocation.

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 no filler; the mutation/confirm nature and the authorization constraint are front-loaded, and the pointer to the sibling tool comes last where it is most actionable.

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

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

For a 5-parameter mutation with no annotations and no output schema, the description covers the highest-risk facts (owner-only, confirm gating, capability constraints). It leaves peripheral gaps around the plain string fields and the response shape, but nothing critical to correct 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 coverage is only 20% (just the confirm parameter), so the description must compensate. It does add real meaning for 'capabilities' by naming the source of valid keys and the delegable exclusions (billing, roster, payouts, ownership), but name, description, and organizationId remain undocumented 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 and resource ('Create a custom gym role') plus its scope ('from delegable capabilities'), which clearly separates it from update_organization_custom_role, delete_organization_custom_role, and list_organization_custom_roles 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 concrete preconditions: 'Owner only', and routes the agent to list_organization_custom_roles to obtain valid capability keys. It does not explicitly say when to prefer this over update_organization_custom_role, but the create-vs-modify distinction is implied strongly enough.

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?

No annotations are provided, so the description carries the full behavioral burden, and it supplies only one fact: that the call is confirm-gated. That fact is already stated verbatim in the schema's 'confirm' description, so it adds little. Nothing is said about authorization requirements, duplicate-location behavior, or side effects such as seat/billing implications.

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 action and target stated first and the gating qualifier last; no filler. It is efficient, though its 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 4-parameter mutation with no annotations and no output schema, so the description should explain permissions, the preview-vs-execute flow, and identifier expectations. Instead it gives one sentence, leaving the agent without enough context to invoke 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 description coverage is only 25% — only 'confirm' is documented, while organizationId, name, and address carry no descriptions. The tool description adds no meaning for any of them (e.g., ID format, address structure, name uniqueness), so it fails to compensate 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 specific verb and resource ('Add a new location/branch to an organization'), so the agent knows this creates a sub-entity of an organization rather than an org itself. It does not name the adjacent siblings it must be distinguished from (update_organization_location, delete_organization_location), but the create 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?

There is no explicit when-to-use guidance, no mention of required permissions or role, and no routing to alternatives. The '(confirm-gated)' parenthetical hints that a confirmation step exists but does not tell the agent when this tool is the right choice over update_organization_location or create_organization.

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

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

With no annotations, the description carries the full burden. It does disclose the confirm-gated preview behavior, which is the most important behavioral trait for a mutation tool, but it says nothing about permissions required, duplicate-prospect handling, or side effects on downstream pipeline state. That leaves meaningful gaps for a write 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 tool's action first and the routing condition after the dash. Dense parenthetical but no filler; it could be split for readability but nothing is wasted.

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

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

For a six-parameter mutation tool with no annotations and no output schema, the description covers purpose, selection context, and the confirm gate, which is the minimum viable set. It leaves permission requirements, duplicate handling, and the meaning of four optional parameters undocumented.

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 17% (just the confirm flag), and the description supplies no meaning for goal, note, email, or phone. The origin story (call, walk-in, referral) loosely implies contact details matter, but no parameter is actually explained 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 specific verb and resource ('add a prospect to the pipeline') and sharpens it with the qualifier 'manually' plus the outside-platform origin, which separates it from automated prospect capture and from siblings like list_prospects or update_prospect_status. It does not name an alternative tool explicitly, 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?

Gives clear selection context: use this when a lead arrived outside the platform, with concrete examples (a call, a walk-in, a referral). That is a real when-to-use signal, though there is no explicit when-not or named sibling to route to 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?

With no annotations, the description carries the full load and does so: plan-tier and confirm prerequisites, per-actionType behavior ('send_message' sends verbatim with template tokens, 'ai_message' drafts in the coach's voice and is held for approval unless requireApproval is false, 'notify_coach' only reminds the coach), and concrete safety limits (8am–9pm client-local, max 2 messages per client per day, each event fires once). That is exactly the kind of side-effect and rate-limit detail an agent cannot get from 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?

The branching structure and safety limits are front-loaded and every clause carries information relevant to correct invocation. It is dense as a single block, and the clause ordering (mode choice, then action semantics, then limits) could be signposted, but 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 9-parameter mutation tool with no annotations and no output schema, this is close to complete: prerequisites, mode selection, action semantics, and rate limits are all covered. The remaining gaps are the undocumented `via` channel and the unspecified valid `triggerType` values, which an agent would still have to guess.

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 11% (just `confirm`), so the description must compensate, and it does explain templateKey, name, triggerType, days, actionType, text, and requireApproval semantics. However, the `via` parameter (chat/push/email) is never mentioned, and `triggerType` is a free-form string with no allowed values given, leaving two of nine parameters 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?

States a specific verb+resource ("Create a workflow") and immediately distinguishes the two creation modes: template-based via `templateKey` or fully specified via `name`/`triggerType`/`actionType`/`text`. It names the sibling that supplies template keys (list_workflow_templates), so an agent can tell this apart from list_workflows and the other workflow tools.

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

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

It gives clear routing between the template path and the custom path, plus the eligibility gate (confirm-gated; Coach Pro or gym plan required) and the direction to obtain keys from list_workflow_templates. It stops short of naming when-not-to-use, e.g. that approval/review flows belong to review_workflow_draft or list_workflow_approvals rather than create_workflow.

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?

No annotations are provided, so the description carries the full burden. It discloses confirm-gating (preview when confirm is false) and, more valuably, idempotency behavior for duplicate client+title calls — real behavioral context beyond the schema. It does not cover permissions/authorization or error behavior, 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?

Front-loads purpose, then routing, then parameter semantics, with every sentence doing work. The modality paragraph and the run-description example are long, but they are load-bearing given the undocumented nested schema; density is justified rather than 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?

For a complex nested-write tool with 25% schema coverage and no output schema, the description covers the hardest parts (modality, section, idempotency, confirm). Minor gaps remain: endDate/description/title semantics and date-range interaction are unaddressed, and return format is not described (acceptable since 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 only 25% and the exercises items are just 'additionalProperties: {}', so the description must compensate — and it does heavily. It defines the exercises object shape, enumerates modality semantics (STRENGTH/INTERVAL/STEADY/AMRAP/EMOM/FOR_TIME/HOLD) with which parameters apply, lists the section enum and its default, and explains exerciseId and notes purpose.

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 with scope: 'Create a workout plan for a client (confirm-gated)'. It also implicitly separates itself from list_workout_plans by naming that sibling as the tool for verification, so an agent can route correctly without opening 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?

Gives explicit when-to-use-elsewhere rules: check with list_workout_plans when asked 'is it done?', call get_training_split first so the week has structure, and pass exerciseId from search_exercises. It also documents idempotency (re-running with confirm:true returns the existing plan), removing ambiguity about repeat calls.

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

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

With no annotations, the description carries the full behavioral burden, yet it only notes "(confirm-gated)" — which the schema already documents in the confirm parameter's description. It says nothing about permissions, scoping, or what persistence actually occurs.

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 core action and constraint; nothing is padded. The cross-reference sentence is terse to the point of being cryptic, 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?

An 8-parameter creation tool with 13% schema coverage, no annotations, and no output schema gets almost no supporting detail here. The agent is left to guess parameter formats and lacks guidance on the template lifecycle, so the description is not complete enough for confident invocation.

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 13% across 8 parameters, so the description must compensate but does not. The note that "exercises follow the same shape as create_workout_plan's" is a cryptic cross-reference that the agent cannot resolve from the current schema, and fields like title, visibility, goal, tags, and difficulty are unexplained.

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 clear verb+resource ("Save a reusable workout plan template") and the word "reusable" implicitly distinguishes the artifact from a one-off plan. It does not directly name create_workout_plan as the non-template sibling it differs from, but the cross-reference to that tool partly signals the relationship.

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: "reusable" hints at when a template is preferable to a plan, but there is no explicit when-to-use, when-not, or naming of alternatives like create_workout_plan or update_workout_plan_template. An 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?

No annotations, so the description carries the full behavioral burden, yet the only disclosure worth noting is '(confirm-gated)' — and the schema's confirm parameter already explains that preview-vs-execute behavior in detail. It says nothing about reversibility, whether scheduled sessions are removed, required permissions, or side effects beyond stopping the class.

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 scoping qualifier front-loaded and zero filler. It is efficient, though its brevity borders on under-specification for a mutation 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 destructive-style mutation with no annotations, no output schema, and a 50%-documented parameter set, the description is too thin. An agent cannot tell whether the action is reversible, what happens to already-scheduled sessions, or how classId is obtained.

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 50%: confirm is well documented in the schema, but classId is not described anywhere and the description adds no format, sourcing, or meaning for it. The description fails to compensate for the undocumented half of the parameters.

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

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

States a specific verb (stop) and resource (recurring class), and the word 'recurring' meaningfully separates it from cancel_gym_class_session, which acts on a single session. It stops short of naming that sibling directly, 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?

Usage is only implied: 'recurring class' hints that this is for whole-series deactivation rather than single-session cancellation, but no alternative tool is named and no condition selects between them. With cancel_gym_class_session, cancel_session, and update_gym_class all in the sibling list, explicit routing would help.

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?

No annotations, so the description carries the full burden. It discloses irreversibility ('for good'), the client-side impact (loss of access), and the confirm gate, but says nothing about permissions/authorization, cascading effects on history or assignments, or error behavior for a destructive 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?

Two tight sentences with zero filler, front-loading the action and permanence before the alternative-tool guidance. 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 no output schema and no annotations, the description does cover permanence, client impact, the confirm gate, and the preferred alternative. It stops short of permission requirements and side effects, but is largely sufficient for a two-parameter delete 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 only 50%: confirm is documented in the schema, while planId has no description anywhere. The phrase 'confirm-gated' merely restates the schema's own confirm semantics and adds no meaning for the undocumented planId, so the description does not compensate 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?

Specific verb+resource (delete a diet plan) with permanent scope made explicit ('for good'). It also states the consequence ('the client loses access to it'), which separates it from the template/workout delete siblings and from update_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?

Gives a clear default-avoidance rule ('prefer editing unless the coach clearly wants it gone'), which effectively steers the agent to update_diet_plan. The alternative is described by intent ('editing') rather than named, so the mapping to the sibling still requires a small 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses that deletion is permanent, that execution is gated behind confirmation, and, critically, the blast radius (existing client plans derived from the template are unaffected). It omits permission/auth requirements, idempotency, and error behavior for a nonexistent 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?

Two short sentences with zero filler; the destructive nature and gating are front-loaded and the side-effect clarification follows immediately. 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?

For a 2-parameter, no-annotation, no-output-schema delete, the description covers permanence, confirmation gating, and non-destructive scope. It is nearly complete, though it could note the absence of a return payload or the effect on marketplace listings set via set_diet_plan_template_marketplace.

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

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

Schema coverage is only 50%: the schema fully documents 'confirm' (including the preview-only behavior of false/omitted) but leaves 'id' with no description. The description's '(confirm-gated)' merely restates what the schema already says about confirm and adds nothing about the id's expected format or reference source.

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 precise verb+resource ('delete a diet plan template') and adds the permanence qualifier. The second sentence separates it from the sibling delete_diet_plan by stating that already-assigned plans are untouched, so an agent can pick the right destructive tool 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?

The '(confirm-gated)' note implies the two-step preview-then-execute flow, but the description gives no explicit when-to-use vs. alternatives (e.g., when to deactivate or update instead, or what preconditions must hold). Usage is only implied by the tool name and the confirm hint.

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

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

With no annotations, the description carries the full burden and does notably well: it discloses the confirm gate, owner-only auth requirement, and the downstream consequence that members holding the role lose its access. It does not describe the preview-vs-execute response behavior, but the schema's confirm field covers 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?

Three tight sentences, all front-loaded with the destructive action and the confirmation gate before the consequence. 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 destructive tool with no annotations, no output schema, and thin schema coverage, the description supplies the critical missing context: privilege requirement, confirmation workflow, and consequence. Only the per-parameter semantics of organizationId/roleId are left thin.

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

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

Schema coverage is only 33% (only 'confirm' is documented). The description compensates partially by emphasizing 'exactly which role' (roleId) and describing the confirmation behavior, but organizationId and roleId formats/scoping remain undocumented. Marginal value above the schema.

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

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

States a specific verb (Delete) and resource (custom gym role), which cleanly distinguishes it from the sibling create_/update_/list_organization_custom_role tools. An agent can identify it without opening the schema.

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

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

Gives clear context: 'Owner only' establishes the required authorization level and 'Get explicit confirmation of exactly which role first' prescribes a precondition workflow. It stops short of naming alternative tools, but the destruction semantics make the routing obvious.

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

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

With no annotations, the description carries the full burden and does disclose the two traits that matter most for a destructive tool: the deletion is permanent and it is confirm-gated. It also flags the non-cascading side effect on coach/client assignments. It omits permission/authorization requirements and what the response returns.

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

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

Two tightly written sentences with no filler; the permanence and the destructive side effect are both 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 destructive, non-read-only tool with zero annotation coverage and no output schema, the description covers irreversibility, the confirm preview gate, and the assignment side effect. It is nearly complete, missing only auth/permission context and the absence of any return-value note.

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

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

Schema coverage is only 50% — the 'confirm' parameter is fully documented in the schema while 'locationId' has no description at all. The description reinforces the confirm gate but adds no identifier format or meaning for locationId, so it only partially compensates for the gap.

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

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

States a specific verb and resource ('Permanently delete a location') with the added qualifier that the deletion is irreversible. It is naturally distinguishable from create_organization_location and update_organization_location, though it never names a 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?

Gives a clear precondition for safe use: coaches and clients assigned to the location are not moved, so they must be reassigned first. It stops short of naming explicit alternatives (e.g. deactivating vs deleting) or stating when deletion is inappropriate.

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

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

With no annotations, the description carries the full burden and does disclose the destructive/permanent nature ('for good'), the confirm gate, and the client-side consequence (loss of access). It omits permissions needed and what a successful deletion returns.

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

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

Two tight sentences, front-loaded with the destructive action and its permanence, then the alternative. No wasted 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?

For a no-annotation mutation tool with no output schema, the description covers the essential behavior: permanence, the confirm requirement, and the safer alternative. Only minor gaps remain (auth requirements, success response).

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%: the confirm parameter is already documented in the schema, while planId is undocumented in both schema and description. The description reinforces 'confirm-gated' but adds no syntax or meaning for planId beyond what the schema implies.

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

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

States a specific verb (delete) and resource (workout plan), reinforced by scope ('for good') and a consequence ('client loses access'). It differentiates the resource from the similarly named delete_workout_plan_template, though it never names a 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?

Gives explicit when-not guidance: 'prefer editing unless the coach clearly wants it gone,' which implies update_workout_plan as the alternative. The condition selecting the alternative is clear, though the alternate tool is not named outright.

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

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

With no annotations, the description carries the full burden and largely succeeds: it declares the operation is permanent/irreversible, notes the confirm gate, and discloses blast radius (assigned client plans are untouched). It omits permissions/authorization requirements and any error or cascade behavior beyond assigned plans.

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 the destructive verb and permanence front-loaded, the confirm gate second, and the side-effect clarification last. 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 two-parameter delete tool with no output schema, the description covers the essential concerns (destruction, confirmation flow, blast radius). It stops short of noting authorization needs or failure modes, but an agent has enough to invoke it correctly.

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

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

Schema coverage is 50%: 'confirm' is fully documented in the schema, and the description only echoes it as 'confirm-gated'. The required 'id' parameter gets no added meaning from the description or schema. Baseline 3 is appropriate given partial coverage and the description adding little 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?

States a specific verb+resource ('Permanently delete a workout plan template') that is unambiguous against siblings like delete_workout_plan and delete_diet_plan_template. The second sentence further pins down scope by clarifying what is not affected.

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 '(confirm-gated)' note implies a two-step preview/execute flow, which is procedural guidance, but the description never says when to choose this over alternatives such as update_workout_plan_template or deactivating. Usage is only 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?

With no annotations, the description carries the full burden. It usefully discloses the confirm gate and the post-condition ('stops showing up and stops nudging'), clarifying this hides rather than deletes progress. However, it omits permissions required, reversibility/undo behavior, and what the preview 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 front-loaded sentence with an em-dash elaboration; every clause adds information (action, scope, gate, effect) and nothing is wasted.

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

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

For a simple 2-parameter mutation this covers the core action and outcome, but with no annotations and no output schema the definition should say more about permissions, whether dismissal is reversible, and how the preview mode behaves beyond what the 'confirm' schema field already states.

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%: 'confirm' is fully documented in the schema, but 'clientId' has no description anywhere. The description's 'a client's' and '(confirm-gated)' only vaguely gesture at both parameters and add no format or identification semantics to compensate for the undocumented clientId.

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 ('Close a client's onboarding checklist') and adds the crucial scope qualifier 'without finishing it', which separates it from siblings like mark_client_onboarding_step and get_client_onboarding. An agent can tell 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?

The phrase 'without finishing it' implies the use case (abandon/stop an incomplete onboarding) and hints at the contrast with completion tools, but it never names an alternative or states when-not to use it. Usage is inferable but not explicit.

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 readOnlyHint annotation already establishes this is a safe read. Beyond that, the description discloses a non-obvious behavioral trait: PHOTO-type answers are transformed into fetchable image URLs, and those URLs are not directly viewable without another call. It omits error behavior and any rate/limit context.

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

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

Two tight sentences, front-loaded with the core action and followed by the one non-obvious caveat. No filler or restated boilerplate.

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, the description covers the action, the shape of the return (questions + latest answers), and the photo-URL caveat. Missing is any note on what happens for an invalid or nonexistent checkInId, but no output schema exists to carry that burden elsewhere.

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

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

Schema description coverage is 0% and the description adds nothing about checkInId — no format, no source, no example. With only one parameter and zero coverage, the description should compensate but does not; the possessive "a check-in's" only implies an identifier is required.

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 ('Get a check-in's questions + latest answers'), which clearly distinguishes it from siblings like list_checkins, create_checkin, and schedule_checkin. The scope of the returned data (questions and latest answers) is explicit.

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

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

It provides concrete workflow routing: photo answers resolve to URLs that must be 'passed into get_client_images to actually view them,' which names an alternative tool and the condition that triggers it. It does not compare itself against list_checkins or note prerequisites, so it falls short of 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 only cover readOnlyHint=true, so the description carries the rest and does add real context: a 'failed' status means the error field is the coach's rejection reason and must be treated as a hard constraint. It does not disclose ordering/limit behavior or what a non-failed run contains, but the added semantic guidance is genuinely 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?

Three short sentences, front-loaded with the action and followed by the interpretation rule and the integration constraint. No filler or 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?

There is no output schema, so the description usefully explains the one output field that drives behavior (error on failed runs). What remains thin is the limit/pagination behavior and the shape of successful runs, but the critical decision-making context is present.

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 two parameters (clientId, limit), so the description is the only place to document them — and it says nothing about clientId's format or limit's default (5) and maximum (20). Neither parameter is explained anywhere, which is a real gap for a 0%-coverage 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: reading a client's past AI Coach runs. The scope is clear and the description also frames why the data matters, though it does not differentiate itself from any near-sibling (none exists in the list, so differentiation is less relevant).

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

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

Explicitly says when to call it ('before building or adjusting their plan') and names the two downstream tools it must precede (create_workout_plan/create_diet_plan). It also gives the interpretation rule for failed runs, removing all 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?

readOnlyHint=true already establishes this is a safe read. The description adds genuinely useful context beyond the annotation: the output is base64-encoded image data intended for visual analysis, which matters because there is no output schema. It doesn't mention the 10-item cap or any rate/size limits, so not full marks.

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 purpose, followed by the input-sourcing instruction. Nothing is padded or 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 no output schema, the description usefully discloses the base64 image return and the source of inputs, which is what an agent needs to chain this after get_checkin_answers. Only the array size limit and format constraints are left 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 description coverage is 0% for the single imageUrls parameter. The description compensates partially by telling the agent where to obtain the URLs (get_checkin_answers's photoAnswers) and implying plurality with 'imageUrl(s)', but it does not explain the 1-10 array bound or accepted URL form.

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 ('Fetch check-in photo(s)'), plus the return form ('base64-encoded image data'), so an agent knows this retrieves images rather than the check-in answers themselves. It distinguishes itself from get_checkin_answers by naming it as the source of the URLs, though it doesn't explicitly contrast with other get_client_* 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?

Gives clear operational guidance: pass imageUrl(s) sourced from get_checkin_answers's photoAnswers. That tells the agent both when this tool is relevant and where its input comes from. No explicit when-not or exclusions, but the context is unambiguous.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: it can return null when none exists or the checklist was dismissed, and it enumerates the status values and fields returned, including auto-setup errors.

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

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

Two dense sentences with the primary resource and scope front-loaded, followed by the return shape. No filler, though the second sentence is quite packed.

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

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

No output schema exists, so the description correctly carries the burden of describing the return value, including field list, status enum, null case, and counts. This is nearly complete for a single-param read tool; only cross-tool routing is missing.

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

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

Schema coverage is 0%, so the description must carry the parameter meaning. It clarifies that clientId is a User _id, which is genuinely useful, but with a single required string param and no format details beyond that, the value added is modest.

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 (the onboarding checklist for one client) and scopes it to a single client identified by User _id. It clearly distinguishes itself from the sibling list_clients_needing_onboarding by being single-client, though it doesn't explicitly name 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?

No guidance on when to use this versus siblings like list_clients_needing_onboarding, dismiss_client_onboarding, or mark_client_onboarding_step. The only condition mentioned is the null case, which describes an outcome rather than when to invoke 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 only declare readOnlyHint=true; the description goes well beyond that by explaining that these are hard constraints enforced server-side (plans violating dietType/foodAllergies/mealsPerDay are rejected; plans requiring unowned equipment are unusable) and that the tool returns null when unset. That is exactly the context an agent needs to interpret 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?

Three sentences, each load-bearing: the field inventory, the hard-constraint consequence, and the timing/null-return directive. No filler, and the consequences and call-timing are front-loaded rather than buried.

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

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

There is no output schema, so the description carries the return-value burden and does so ('Returns null if they have not set any') while also listing what a non-null result contains. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 0%, so the lone clientId parameter is undocumented in both places. However, clientId on a get_client_preferences tool is self-evident in meaning, and the description does not need to invent syntax for it. Baseline 3 for a trivially-named single parameter with no added semantics.

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 resource (the client's own stated constraints) and enumerates its contents — diet type, allergies, cuisines, meals per day, training days, equipment, session length, notes. This is clearly distinguishable from neighboring getters like get_client_profile or get_client_onboarding, 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 gives an explicit when and a why: 'Call this BEFORE create_workout_plan/create_diet_plan on every run, including weekly adjustments.' It even pre-empts the common mistake of reusing stale data ('clients change these between runs'). This is the strongest form of routing 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?

readOnlyHint=true already establishes this is a safe read, lowering the burden. The description adds the concrete return contents, which is genuinely useful context, but discloses nothing about authorization scope, pagination, or error behavior for an invalid clientId.

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 zero filler; the return-value summary is front-loaded and the parameter guidance follows immediately. Nothing is redundant with the schema or annotations.

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

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

With no output schema, the description takes on the job of describing what comes back and does so by naming the key metrics. Combined with the alias clarification, an agent has enough to invoke it correctly; only the distinction from adjacent client getters is 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 0%, so the description carries the full parameter burden, and it does so well: clientId is identified as the client's user _id, the same value used by every other tool, and userId is flagged as an accepted alias. This resolves the ambiguity of two overlapping optional string params that the schema leaves completely undocumented.

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

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

States a specific verb and resource ('Get a client's fitness profile') and enumerates the computed metrics returned (BMI, TDEE, recommended calories, weights), so an agent knows what it produces. It implicitly separates itself from the self-scoped get_my_profile by saying 'a client's', but never names a 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?

The description tells the agent which identifier to pass and that userId is an alias, which is useful invocation guidance, but gives no when-to-use versus when-not guidance relative to get_my_profile, get_client_preferences, or the other client getters in the sibling list. Usage is implied 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?

Goes well beyond the readOnlyHint annotation: it discloses the shape of the returned data, the special document-only PDF case, and that a null document.text signals a scanned/unreadable PDF. It even supplies the remediation step (tell the coach to use 'Turn into a trackable plan'), which an agent could not infer elsewhere.

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 payload summary, then the edge cases in logical order; no filler. Slightly dense with nested backticked references, but every sentence carries operational value.

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

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

There is no output schema, so the description carries the return-value burden and does so thoroughly, including the degenerate PDF-only case and null handling. Nothing an agent needs to call and interpret the result is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it tells the agent the parameter is the plan _id sourced from list_diet_plans. It stops short of stating format constraints (e.g., string/ObjectId expectations), so not a full 5.

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

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

States a specific verb and resource ('Full detail of one client diet plan') and enumerates exactly what the response includes (time, section, calories, macros, ingredients, notes, PDF text). This clearly separates it from list_diet_plans and get_diet_plan_template in the sibling set.

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

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

Explicitly tells the agent to pass the plan _id from list_diet_plans, establishing the correct call sequence. It also gives conditional handling for the document-only case, though it does not explicitly contrast against get_diet_plan_template or list_diet_plans by 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower; the description adds the useful disclosure that the response is the full detail including every meal. It does not say what happens with an unknown or stale id, nor whether the template is returned inline or expanded.

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 efficient sentence with the scope front-loaded and no filler. It is not padded, though it is also too terse to carry the detail the tool needs.

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 partially compensates by describing the return payload ('including every meal'), and readOnlyHint covers safety. Missing is any hint about the id's origin or lookup failure behavior, which matters for a lookup tool keyed on an opaque identifier.

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

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

Schema description coverage is 0% for the lone required 'id' parameter, so the schema supplies no meaning at all. The description only implies that 'one' template is selected by the argument; it never states what the id identifies or its format, leaving the coverage gap uncompensated.

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 (get/full detail) and resource (one diet plan template) and scopes the payload (including every meal), so it is distinguishable from list_diet_plan_templates by the word 'one'. It stops short of naming the sibling tools it differs from.

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 mention of prerequisites, and no reference to the list_diet_plan_templates alternative that would supply the required id. The single-template scope is only implied by the phrase 'one diet plan template'.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's job is lighter. It does add value by enumerating the returned dimensions (booked/attended/no-show counts, per-class fill rate), but it says nothing about how the aggregation is scoped, how missing data is treated, or what granularity (per class? per member? totals) the summary uses.

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 metric content front-loaded and no filler. It is efficient, though the terseness contributes to the gaps in usage and parameter guidance rather than being purely a virtue.

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 0% parameter coverage, the description is the only place an agent could learn the return shape, granularity, or date semantics, and it does not. The readOnlyHint annotation covers safety, but an analytics tool whose output structure and scoping rules are undefined is under-specified.

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

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

Schema description coverage is 0% across three parameters, so the description carries the full burden. It only gestures at 'a date range', which loosely maps to from/to but gives no format, inclusivity, or default, and it never explains that organizationId is required and scopes the result.

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 resource and metric set: member attendance broken into booked/attended/no-show plus per-class fill rate over a date range. An agent can tell this is an aggregate attendance-report tool rather than a roster or a write path, but it never names the neighboring tools (e.g., get_gym_class_roster, get_organization_coach_attendance) that could be confused with it.

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 mention of 'over a date range' implies a period-reporting use case, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives. For a tool sitting next to get_gym_class_roster, mark_gym_class_attendance, list_gym_class_sessions and get_organization_coach_attendance, that absence is a real selection hazard.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful content context (attendance status is included in the result), but says nothing about permissions, pagination, or result 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 sentences, zero filler, with the tool's output scope front-loaded and the prerequisite second. 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?

For a one-param, read-only tool with no output schema, the description covers what it does, what it returns at a high level, and where the id comes from. Only the precise return shape and any authorization requirements are left 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 0%, so the description carries the burden, and it does add meaning: the single sessionId refers to a class session and should be sourced from list_gym_class_sessions. It stops short of giving the id format or any validation 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+resource (roster of one class session) and its content scope (who is booked and whether they attended). It is clearly distinguishable from list_gym_class_sessions, which it explicitly names as a different tool.

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

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

Gives a concrete prerequisite: use list_gym_class_sessions to obtain the session id. It does not, however, address when this roster is preferred over related reads such as get_gym_attendance_summary or mark_gym_class_attendance, so the exclusion guidance is incomplete.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine value on top: it discloses that results are role-scoped and that fields the coach's role cannot see are returned as null, which an agent cannot infer from 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 dense sentences with no filler, and the core scope statement is front-loaded before the null-behavior caveat. Every clause carries information.

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

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

With no output schema, the description properly carries the return-value burden by enumerating the fields returned. It falls short only on the parameter and on sibling disambiguation, but the data-shape coverage is strong for a one-param read tool.

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

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

There is one required parameter (organizationId) with 0% schema description coverage, and the description never mentions it, its format, or that it identifies the gym being viewed. The description fails to compensate for the total lack of schema documentation.

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 clear verb+resource ('gym overview') and enumerates the exact data returned (client/coach counts, revenue, leads, classes, announcements, billing). However, it never distinguishes itself from the overlapping sibling get_organization_dashboard, leaving the agent to guess which overview 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 description implies a dashboard-style read but gives no when-to-use guidance, no conditions selecting it over get_organization_dashboard or get_organization_earnings, and no prerequisites. The role-scoping clause is the only contextual cue.

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, indicating no side effects. The description adds that the return value is a percentage between 0 and 100, which is helpful. It does not disclose computation details or error handling, but for a simple read operation with annotations, the description adds sufficient context.

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

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

The description is a single sentence that concisely conveys the essential information: what the tool returns, its range, the client context, and the date format. No unnecessary words or 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?

Given the tool's simplicity (3 required parameters, no output schema), the description covers the core functionality well. It does not explain what happens if no data matches or if parameters are invalid, but for a straightforward query tool with good annotations, it is mostly 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?

The schema has 0% description coverage on parameters. The description explains that the tool operates on a client over a date range and specifies the date format (YYYY-MM-DD), which adds value. However, it does not clarify constraints like startDate before endDate, boundary behavior, or the meaning of clientId beyond being required.

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

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

The description clearly states that the tool returns a habit compliance percentage (0-100) for a client over a date range. It specifies the resource (habit compliance), entity (client), and filter (date range). While it does not explicitly differentiate from siblings like 'recent_habit_activity', the purpose is distinct and 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?

The description provides no guidance on when to use this tool versus alternatives, such as 'list_client_habits' or 'recent_habit_activity'. There is no mention of prerequisites, edge cases, or when not to use it, leaving the agent without context for 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 only declare readOnlyHint=true, and the description adds substantial behavior beyond that: results are ranked by matchConfidence, each result carries a typicalServingG anchor and an isCookingAddition flag, and it prescribes fallback handling ('estimate sensibly and still list it — never drop the cooking fat'). This is rich operational context an agent could not infer from the annotation.

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 fairly long paragraph, but it is front-loaded with what the tool returns and each sentence adds distinct value (what it returns, when to call it, query format, scaling math, fallback). No filler or restatement of the tool name is present.

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 usefully enumerates the returned shape (macros, matchConfidence, typicalServingG, isCookingAddition) plus the scaling instruction, so an agent can act on results. The only material gap is the undocumented `limit` parameter, which slightly undercuts completeness for a 2-param tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does explain the `query` parameter well (plain name, with examples like 'paneer', 'cooking oil'), but the `limit` parameter (default 5, max 20) is never mentioned, leaving one of two parameters undocumented in both schema and description. Partial compensation warrants a mid score.

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+resource combination ('Per-100g nutrition ... for raw ingredients') and pins the data source ('from the platform's curated table'). It gives the returned macro fields explicitly, so an agent knows exactly what this tool produces and how it differs from sibling retrieval tools like get_client_preferences or search_exercises.

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

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

It states the usage context clearly ('Call this while building a diet plan to itemise each meal into real raw materials ... instead of guessing per-food macros') and even gives fallback behavior when an ingredient isn't found. It does not name an explicit alternative tool to use instead, but the sibling list is largely CRUD/plan-management, so the routing guidance is adequate without 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful scoping context (invitations received by this coach that are still pending), but says nothing about return shape, pagination, or how 'pending' is determined.

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 resource and immediately tightened by the scope qualifier and a parenthetical example. 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?

For a zero-parameter read tool with annotation coverage, this is nearly sufficient. The only residual gap is that no output schema exists, so the agent cannot know the return structure — though that is arguably acceptable for a simple list.

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 for a no-param tool.

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 (organization invitations) with clear scope qualifiers: received by this coach and not yet responded to. The staff-invite example grounds the concept concretely. It does not, however, distinguish itself from the sibling list_invitations, so an agent cannot be certain which to pick without opening both.

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 mention of alternatives. With siblings list_invitations and list_my_organizations present, the definition leaves the selection decision entirely 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?

readOnlyHint=true already covers the safety profile, so the bar is lower, and the description adds real value on top: it declares the content domains returned and explicitly excludes bank details. That exclusion is a meaningful behavioral constraint given the sibling update_my_bank exists. It does not cover any failure modes or rate/auth behavior, so it falls short of a 5.

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

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

Two tight sentences, with the scope ("the coach's own full profile") front-loaded and the content enumeration following immediately. The bank-exclusion caveat is placed last as a qualifier, and no sentence is redundant with the 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?

There is no output schema, so the description carries the burden of describing return content, and it does so by naming the major field groups. Combined with the readOnly annotation and the zero-parameter schema, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, which is the baseline-4 case: there is nothing for the description to document beyond what the schema already shows. No parameter syntax, filtering, or format guidance is needed or missing.

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 clear verb+resource ("The coach's own full profile") and enumerates the returned domains: contact info, professional info, availability, and transformations/testimonials. The phrase "coach's own" usefully separates it from sibling get_client_profile and get_organization_profile, though it does not distinguish itself from whoami, which likely overlaps.

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 infers it should call this when it needs the authenticated coach's profile. There is no explicit when-to-use guidance, no statement of when to prefer whoami or get_client_profile instead, and no prerequisites or auth notes beyond the annotation.

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, so the safety profile is covered. The description goes beyond that by disclosing the visibility filter (private ratings excluded) and result ordering ('newest first'), which are genuine behavioral traits an agent cannot get from annotations. It stops short of describing pagination behavior for the limit parameter.

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 scope constraint and ordering both earn their place, and nothing is repeated from structured fields.

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 no output schema and one optional param, the description covers what is returned (public client reviews) and how it's ordered. The only gap is the undocumented limit/pagination semantics, which is a minor omission otherwise.

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 parameter (limit) has 0% schema description coverage — the schema only supplies min 1 / max 100 bounds. The description never mentions the limit or its default, so an agent gets no semantic guidance on controlling result size. This is the weakest area for a one-parameter tool with no schema documentation.

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

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

States a specific resource (the coach's own client ratings/reviews) with clear implicit verb (retrieve/list) and scope (own, public only). An agent can infer this returns individual reviews rather than aggregate stats, distinguishing it in spirit from get_my_rating_summary, though the sibling is never named.

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

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

Usage is implied by 'the coach's own' — you call it to read your own reviews — and the 'public ones only' clause hints at what will and won't appear. However, no alternative is named (get_my_rating_summary exists as an obvious sibling) and there is no 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?

readOnlyHint=true already tells the agent this is a safe read with no side effects, so the description's burden is reduced. It adds the useful detail that the result is an aggregate (average plus count) rather than raw reviews, but does not describe formatting, scoping, or failure behavior. Adequate against the annotation baseline, not rich.

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

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

A single short sentence with no wasted words. It is a noun fragment rather than a verb-first construction, which slightly weakens front-loading, but nothing could be 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 zero-parameter read tool with no output schema, the description adequately signals the two values returned (average rating, review count) and the read-only nature is covered by annotations. The one gap is that it never clarifies its relationship to get_my_ratings.

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 schema has nothing to document and the baseline is 4. The description correctly implies no input is needed and focuses on output content instead.

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 coach's star rating) and implies the read verb via the tool name, and states the returned metrics (average rating and review count). It is clear what the tool does, but it does not explicitly distinguish itself from the sibling get_my_ratings, leaving the agent to infer that this is an aggregate summary rather than a review 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?

There is no when-to-use guidance, no prerequisites, and no mention of the closely related get_my_ratings sibling. The agent must infer usage entirely from the name and 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?

readOnlyHint=true already covers the safety profile. On top of that, the description discloses return content that has no output schema to carry it: the role, the exact capabilities granted, and the custom role's name. Useful behavioral context beyond the annotation.

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: what is returned first, then the usage directive. No filler, and the most decision-relevant content 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 simple single-param read with no output schema, the description covers both the returned data (role, capabilities, custom role name) and the call-first usage pattern. Only the organizationId parameter's semantics are left unaddressed.

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

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

Schema description coverage is 0% and the description never mentions organizationId or its expected format. The phrase "in a gym" implies org scoping, but the single required parameter is left to be inferred from its self-explanatory name. With no schema documentation, the description should compensate more than it does.

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: retrieves the coach's own role in an organization plus the capabilities it grants. This is distinguishable from siblings like get_organization_role_guide (generic role docs) and get_organization_profile, though those siblings are not named. Clear but without explicit sibling differentiation.

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

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

"Call this first to know which gym tools this coach may use" gives an explicit, actionable directive for when to reach for the tool. No when-not condition or named alternative is provided, which keeps it below 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=true, so safety is covered and the bar for added context is higher. The description adds no behavioral detail beyond scoping words already implied by parameters: no permissions required, no pagination/size limits, no statement of what the roster contains (coach identities, attendance status).

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 fragment with zero padding, which is structurally fine, but it is terse to the point of under-specification rather than genuine conciseness – the brevity comes at the cost of any usage or parameter guidance.

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

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

For a 3-parameter tool with 33% schema coverage and no output schema, the definition should clarify the org/location relationship, the optionality of locationId, and what fields the roster returns. It does none of that, so an agent could easily call it with the wrong scope or misinterpret the result.

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

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

Schema description coverage is only 33% – only attendanceDate is documented ('YYYY-MM-DD'). The description's 'for one date' loosely reinforces the date and location framing, but it says nothing about organizationId or about locationId being optional rather than required, leaving the two undocumented parameters unexplained in both places.

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 phrase 'A location's coach attendance roster for one date' names a concrete resource and its scope (coach attendance, single location, single date), so an agent can tell what it retrieves. However, it is a bare noun phrase with no verb, and it never contrasts with the write-side sibling record_organization_coach_attendance, so the read/write distinction is left to inference.

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 at all: no prerequisites, no indication of whether organizationId must match the location's org, and no mention of the obvious alternative record_organization_coach_attendance (or get_gym_attendance_summary). The agent must infer everything 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, so safety is covered. The description adds the useful scope statement that data is aggregated overall plus per-location and per-coach, but says nothing about time range, permissions needed, or freshness of the totals.

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 efficient sentence with the main payload (clients and revenue totals) front-loaded. No filler, though it is terse enough to leave gaps unaddressed.

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 aggregation tool with no output schema and three undocumented parameters, the description omits the reporting period, whether coachId/locationId narrow or expand results, and required access level. It is not adequate to call the tool confidently beyond the happy path.

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 all three parameters, so the description carries the full burden and fails to say what organizationId, coachId, or locationId do. It only obliquely implies filtering via the 'per location and per coach' breakdown, which is not tied to the actual filter parameters.

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

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

States a specific resource (organization-wide totals) and enumerates its content: clients and revenue, broken down per location and per coach. It is clear, but it does not distinguish itself from overlap-prone siblings such as billing_summary, get_organization_earnings, or get_gym_home.

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 named alternatives, despite several sibling tools that also surface revenue or organization-level aggregate data. The agent must infer which dashboard-type tool to pick.

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

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

readOnlyHint already marks this as a safe read, and the description adds genuinely useful operational context: amounts are in the smallest currency unit and payouts are settled outside the app (so the returned data is informational, not actionable here). This is real disclosure beyond the annotation, though it says nothing about permissions or result size.

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: purpose first, then the currency-unit caveat, then the settlement note. Every sentence carries distinct information with no filler, and the most important framing 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?

With no output schema, the description usefully previews the return shape (total, per-coach breakdown, per-payment detail, payout mode), which is what an agent needs to judge relevance. The main gap is date-range parameter conventions, which the schema does not cover either.

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 all three parameters. The phrase 'for a period' loosely implies that from/to bound the date range, but the description never explains the expected date format or what from/to mean relative to each other, leaving the undocumented parameters largely unexplained.

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+resource (earnings statement) and enumerates its contents: total, per-coach totals, each payment with seller and current coach, and payout mode. That level of specificity separates it from a raw sibling like list_organization_payments, though no sibling is named explicitly.

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

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

It states the tool covers 'a period' but gives no when-to-use guidance, no exclusions, and no pointer to alternatives such as billing_summary or list_organization_payments. The agent must infer the choice entirely.

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, so the safety profile is covered. The description adds useful content-level disclosure by enumerating the returned sections (locations, coaches, roles, assignments, pending invites), but says nothing about permissions needed, payload size, or pagination behavior.

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

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

Two tight sentences with no waste; the resource contents are front-loaded and the prerequisite tip 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 read-only tool with no output schema and one required param, the description adequately covers what comes back and where to get the id. Minor gaps remain around auth expectations and response shape, but nothing essential to invoking 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?

With a single parameter at 0% schema description coverage, the schema alone offers no meaning. The description compensates by explaining where to source the organizationId (list_my_organizations), which is exactly the missing guidance, though it doesn't describe the id's format.

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 (full org structure) and enumerates exactly what it contains: locations, coaches with roles and assigned locations, and pending invites. This composite scope implicitly distinguishes it from siblings like list_organization_locations or list_organization_coaches, though it never names 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?

Provides clear context by directing the agent to list_my_organizations to obtain the required id, which is a real prerequisite. It does not, however, state when this composite fetch is preferable to calling the narrower list_* siblings, nor any 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful scope context by framing the content as public-facing profile plus settings, but it does not disclose whether the caller must be a member/admin of the org, whether any fields can be null, or anything about access restrictions.

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 payload description and then the id-routing hint. The field enumeration is dense but each item conveys distinct return content, and 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?

With no output schema, the description carries the return-value burden and does so by listing the fields returned, which is the key information an agent needs. Combined with readOnlyHint covering safety, the only real gap is access/prerequisite context.

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 (organizationId) with 0% schema description coverage, so the schema alone leaves its origin ambiguous. The description partially compensates by pointing to list_my_organizations as the source of the id, but does not clarify the expected format or whether it must be an org the caller belongs 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?

The description names the resource (a gym's public-facing profile and settings) and enumerates the specific fields returned (description, contact, city, slug/visibility, branding, community switch, AI guidelines, payout mode), which lets an agent distinguish it from siblings like get_organization_dashboard or get_organization_access. It stops short of explicitly contrasting with update_organization_profile, so it is clear but not fully sibling-differentiated.

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 provides one concrete routing hint — 'Use list_my_organizations for the id' — which tells the agent how to obtain the required parameter. However, it gives no guidance on when to prefer this tool over the other organization-read siblings (dashboard, access, earnings), leaving selection largely 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?

readOnlyHint=true already establishes this is a safe read, so the description's burden is lighter. It adds the useful scoping detail that only built-in roles are covered, but says nothing about whether the result is static or org-dependent, nor why an organizationId is required for what sounds like global reference data.

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

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

A single front-loaded sentence with no filler. Efficient, though it is a fragment that omits any verb framing what the caller receives.

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 a readOnlyHint annotation, the description carries real burden. It conveys the conceptual content (role permissions) but leaves the required parameter and the nature of the returned guide unexplained, so it is only minimally 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 coverage is 0% and the single required parameter organizationId is never mentioned in the description. This is especially problematic because the tool describes static built-in role definitions, so an agent has no clue what the org ID scopes or whether it is simply an auth/context argument.

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 resource (built-in gym roles) and enumerates the exact roles covered (OWNER, ADMIN, PRIMARY_COACH, COACH). The verb is implicit — it reads as a reference lookup rather than stating 'returns the permission guide' — but an agent can distinguish it from siblings like get_organization_access or get_organization_hierarchy.

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 mention of alternatives (e.g. list_organization_custom_roles for non-built-in roles), and no prerequisites. The only hint is that this covers built-in roles, which implies custom roles live elsewhere, but that 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful content-level context by enumerating the billing states (NONE/TRIAL/ACTIVE/CANCELLING/PAYMENT_FAILED/ENDED) the response can contain, which is behavior beyond the annotation. It says nothing about permissions/scoping for the organizationId or pagination, but that is a small gap for a read-only usage lookup.

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, front-loaded with the primary fact (seats used vs. limit) followed by the secondary billing fields. No filler text, though the long parenthetical enum list makes it slightly clunky.

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

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

With no output schema, the description carries the burden of describing returns and does so reasonably by enumerating the key fields and billing states. It is still incomplete on parameter meaning and organization scoping, which an agent needs 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 0% and the sole parameter organizationId is undocumented in both the schema and the description. The description does not clarify that the caller must supply an organization identifier or how it is scoped, so it fails to compensate 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?

The description states the resource clearly (coach seat usage vs. plan limit) and enumerates the returned data: billing state, renewal date, scheduled cancel/downgrade, and over-limit coaches. It is distinguishable from most siblings by its specific seat/billing focus, though it never names an alternative. A specific verb is implied by the get_ prefix 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?

No when-to-use guidance is given and no alternative is named. Siblings such as billing_summary, get_organization_dashboard, get_organization_earnings, and list_organization_seat_tiers overlap in the billing/seat space, so an agent gets no help deciding between them.

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

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

Annotations only declare readOnlyHint=true; the description goes well beyond that by disclosing the output nature (aggregated category counts, no raw rejection text), the privacy guarantee, and how the result should be interpreted relative to client-specific data. That is rich behavioral context an agent could not infer from structured fields.

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

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

Front-loaded with purpose, then weighting guidance, then precedence rule. Three sentences that each carry information, though the interpretation guidance could be slightly tighter.

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

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

No output schema, and the description does cover the return shape (category counts) and the read-only nature. The only real gap is the sinceDays parameter's meaning, which is left entirely to the schema.

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

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

There is one parameter (sinceDays) with 0% schema description coverage, and the description never names it or explains its window; 'recently' only loosely gestures at the time range. With an undocumented parameter, the description should compensate but 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 (check) and resource (platform-wide coach rejection trends) and clarifies the return shape: 'as category counts (never any client's raw rejection text)'. It explicitly contrasts itself with get_client_ai_history, so an agent can distinguish it from the 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?

Gives explicit when/when-not guidance: use as a 'secondary caution alongside get_client_ai_history, not a hard constraint', apply the 30%-dominance heuristic, and defer to the client's own data. Nothing is left to inference about how to weight the signal.

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, so safety is covered. The description adds that the output is aggregated counts scoped to the coach, which is useful, but it omits whether the counts are time-windowed, whether 'legacy lost' is consolidated, or how zero-count stages appear.

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; the parenthetical stage list is long but carries real information about the returned buckets. It could trim 'for the coach' redundancy but is otherwise tight.

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

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

With no output schema, the description correctly compensates by enumerating the stage buckets the counts are keyed by, which is the key thing an agent needs. It stops short of describing ordering, totals, or time scope, leaving a small 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; baseline 4 applies. The enumerated stage names actually describe the shape of the result categories rather than any input.

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