Phorme Training

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

Beyond the destructiveHint/openWorldHint annotations, it discloses the full consequence tree: accept books the member (paid class held while they pay on Phorme's page, full class lands them on the waitlist, 1:1 requests forwarded to the place's email), decline ends it with the owner's note, and either way the member is notified. It also states auth prerequisites (a connected Phorme account that owns the place, and the gym plan at that place), the plan_url result, and explicitly that it takes no payment.

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

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

Front-loaded with the 'Use this when' trigger and tightly packed with consequence detail; nearly every sentence earns its place. It runs long and repeats the 'at their place' scoping, but no sentence is filler.

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

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

For a destructive, open-world mutation with an output schema already present, the description covers trigger, workflow gate, downstream effects, auth requirements, and payment behavior. An agent has everything needed 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 75% and the schema already documents note, hold_id, and confirmation. The description still adds real meaning: it constrains confirmation to the post-verbal-yes moment and frames hold_id as coming from list_held_requests, tying the parameter to a concrete workflow.

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 pair (accept/decline) and the exact resource (one ask held for the plan at their place, identified by hold_id). It is distinguishable at a glance from list_held_requests, which only surfaces the holds this tool answers.

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

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

It names the trigger condition ('when an owner wants to accept or decline one ask held for the plan at their place') and imposes a mandatory pre-step: read the ask back to the owner and only set confirmation=true after they said yes. That is explicit when/when-not with a workflow gate, not vague 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?

Goes well beyond annotations: enumerates all four outcome states (booked, waitlist, 15-minute hold for paid classes, request forwarded when booking isn't open), states the permission prerequisite (training:write), and clarifies that no payment, payment link, amount, or subscription is involved. It also discloses idempotent behavior with the concrete consequence ('same class again returns the same booking'), complementing the idempotentHint 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?

Front-loaded with the trigger and the confirmation requirement, then the outcome model, then guardrails. The payment clause is somewhat repetitive ('takes no payment, gives no payment link, names no amount') but each variant guards a distinct failure mode, so the length is largely earned.

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 annotations covering safety/idempotency and an output schema covering return values, the description still supplies the things structured fields can't: the outcome branching, the auth requirement, the confirmation protocol, and the explicit payment boundary. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so class_id, place_id, and confirmation are already fully documented, including the const:true constraint and the find_gym_class provenance. The description reinforces the confirmation semantics but adds no syntax or format detail beyond the schema — baseline 3 is appropriate.

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

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

Specific verb + resource + scope: 'book a place in one class at a Phorme gym or studio' for the connected account. An agent can distinguish it from find_gym_class (discovery) and cancel_gym_booking (reversal) without opening any schema.

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

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

Explicit trigger ('when a signed-in user wants a place in one class') plus a mandatory pre-step ('confirm the class, the day and time, and the gym with the user first, and set confirmation to true only after they said yes'). It does not name find_gym_class as the required discovery alternative, but the dependency is stated in the schema rather than the description.

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

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

Annotations already flag destructiveHint and openWorldHint, and the description adds real behavioral context beyond them: it frees a waitlist spot, paid classes are not refunded ('sales are final'), confirmation must be true only after user consent, and the training:write permission is required.

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 trigger and consent requirement, and each sentence carries information (permission, no-refund, waitlist effect). Slightly repetitive on the id parameters, which the schema already covers.

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, open-world mutation with an output schema present, the description supplies everything an agent needs: consent sequencing, auth requirement, refund consequence, and id alternatives. Return values are covered by the output schema.

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

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

Schema coverage is 100%, so the schema already documents class_id, booking_id and confirmation. The description restates the either/or id choice and the confirmation gate without adding format or edge-case detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('cancel a Phorme gym booking') and enumerates the covered cases (booked class, waitlist, gym request). An agent can immediately distinguish it from booking-oriented siblings like book_gym_class.

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

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

Explicit when-to-use trigger ('when a signed-in user wants to give up a class'), plus a required confirmation workflow and the permission prerequisite. It does not name a direct alternative tool, but the cancellation-vs-booking split is unambiguous from the name and 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?

Adds substantial context beyond the annotations: up-to-a-minute latency, reuse of a check from the last week, that the result is saved as a share page, that nothing about the place on Phorme is changed, and the 'free next step' claim link. These details reconcile with readOnlyHint=false and idempotentHint=true rather than contradicting them.

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

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

Front-loaded with the usage trigger and examples, then behavior and return values, so an agent can stop reading early. However it is a single dense paragraph of roughly ten sentences with some enumerative redundancy that could be tightened.

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 an output schema, the description still covers the essentials an agent needs: who it is for, what it consults, latency, caching, side effects, and the shape of the answer. Nothing required for 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 description coverage is 100%, so place, city, and the kind enum are already documented. The description does clarify race-specific meaning ('where it starts', 'race date') and the customer-facing framing of kind, but adds no syntax or format guidance 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?

Names a specific operation (asks OpenAI's model with web search two customer-like questions about a place or race) and enumerates precisely what it returns: found/not found, named among the best and who instead, five stated facts, cited pages, and a result link. This is clearly distinguishable from siblings like get_gym_report or claim_place.

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

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

Gives an explicit trigger (owner or manager asking whether ChatGPT knows or recommends their place) with concrete example phrasings, and an explicit exclusion ('for owners and managers, not for rating a place for someone choosing where to go'). It stops short of naming a specific alternative sibling for the excluded case.

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

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

Annotations only say this is a non-read-only, open-world, non-destructive write. The description adds substantial behavior the annotations cannot convey: it does not transfer ownership by itself, a six-digit code goes to the contact on file (not the requester), the code entry completes the handover, places with no contact wait for Phorme's team, and no payment is taken.

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 trigger condition leads, then the mechanics, then constraints — a sensible order for an agent. It is a bit long, with several clipped sentences ('It takes no payment. It needs a connected Phorme account.'), but each carries distinct constraints 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 multi-step, manually-verified claim flow, the description covers eligibility, the consent gate, the out-of-band code path, the no-contact fallback, cost, and account requirements. An output schema exists, so return values need not be explained.

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

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

Schema description coverage is 100%, so place_id, via, and confirmation are already documented including the enum default and the const:true constraint. The description reinforces confirmation's intent but adds no syntax, format, or edge-case detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource (claim a place) and pins down the exact situation: a place Phorme already lists that nobody runs on Phorme. That condition implicitly separates it from create_or_claim_place (unlisted places) without naming the sibling, which is a minor gap but the scope is unambiguous.

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

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

It gives an explicit trigger with a quoted owner utterance ("that gym is mine"), states the prerequisite (connected Phorme account) and the operational instruction to confirm with the owner before setting confirmation=true. Nothing about when to use it 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?

Goes well beyond the annotations: it reveals that the code-only form changes nothing, that the name+confirmation form creates a draft copy with rules and programs, that the originating coach keeps 10% of earnings, and that a connected account is required. These are material behavioral facts an agent could not infer from readOnlyHint/destructiveHint alone.

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

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

Front-loaded with the 'Use this when...' trigger, then the two modes and the account/confirmation caveats. It is a dense paragraph rather than bulleted, but every sentence carries actionable information with no filler.

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

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

With full schema coverage, an output schema, and non-destructive annotations already present, the description fills exactly the remaining gaps: when to use it, what each mode does, the royalty side effect, and the confirmation gating. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the code-only vs code+name+confirmation branching and the ordering constraint that confirmation should be true only after the coach has agreed and chosen a name. This clarifies how parameters combine, not just what they are.

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

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

States a specific verb and resource ('copy' a 'coaching brain from a code') and distinguishes itself from siblings like find_coaching_brain and start_my_coaching_brain by describing the copy-from-another-coach scenario. The example phrase ('start my brain from K7Q2-XR4D') anchors the intent unambiguously.

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

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

Gives a clear triggering condition ('when a coach has another coach's Phorme code and wants to start their own coaching brain from it') and explains the two invocation modes (code alone for preview, name+confirmation for copy). It does not name specific alternative siblings, so it stops short of full 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 declare the generic profile (destructive, not read-only, open-world). The description goes well beyond: invite sends the phone an SMS, the member is notified once when covered or removed, cover counts only while the gym plan covers the place up to its cap with normal payment beyond it, no payment is taken here, and a connected Phorme account owning the place is required. These are exactly the side effects and prerequisites an agent needs.

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

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

Front-loaded with the triggering situation and packed with signal, with no filler sentences. It is a dense single paragraph though, mixing invocation guidance, side effects and billing caveats, so scanning is slightly harder than a structured layout would be.

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

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

With an output schema available, return values need not be explained, and the description still covers auth prerequisites, the confirmation gate, notification side effects, and the billing cap. Nothing essential for correct invocation is missing apart from the sibling-tool routing.

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

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

Schema coverage is already 80%, so the baseline is 3, but the description adds real meaning: phone is specifically for invite, member_id is for approve/remove and comes from action=list, and confirmation must be true only after the owner verbally agrees. That maps the enum values to their required parameters in a way the schema 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?

The description states a concrete verb set (list/invite/approve/remove) against a specific resource (one member's cover on the owner's gym plan), so an agent knows exactly what the tool does. However, it never names the obviously related sibling set_member_cover, so the one-member-vs-bulk distinction has to be inferred from the title.

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 when-to-use context ('an owner on the gym plan wants to see who is covered... or to invite, approve or remove one member') and even a sample utterance. It also prescribes the read-back-and-confirm protocol for the mutating actions. It stops short of naming when NOT to use it or pointing at an alternative tool.

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

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

Beyond the annotations (which only declare readOnly=false, destructive=false, openWorld=false), the description discloses that the result is an invisible draft, that page facts are captured and the map pin is derived from the address, that an existing name+city match is returned unchanged, that no payment or plan starts, and that a connected Phorme account is required.

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 front-loaded with the when-to-use trigger, then the confirmation workflow, then side effects and constraints, then the account prerequisite. Every sentence carries a distinct fact (draft visibility, pin lookup, idempotency, no charge) 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 an 18-parameter mutation with an output schema available, the description covers all that remains necessary: purpose, trigger, human-confirmation requirement, side effects, idempotency, cost posture, and auth prerequisite. Return values are correctly left to the output schema.

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

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

Schema description coverage is 94%, so the schema already documents all 18 fields thoroughly. The description only reiterates the confirmation gating and the address-to-pin behavior, which the schema already states, so it adds little new parameter meaning beyond the baseline.

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

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

The description states a concrete verb and resource (list/claim the owner's place on Phorme) and pins down the exact scope: a private draft that nobody else sees. It also implicitly separates the operation from publishing/updating by describing the draft-only, idempotent claim behavior.

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 names the precise trigger ('when a gym, studio or clinic owner wants their place on Phorme, for example after an AI check, or says "list my gym"') and the required precondition workflow (confirm name, city and address; set confirmation=true only after the owner agrees). This is explicit both about when to reach for the tool and how to gate 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that results are capped at five, ordered nearest or best matching first, and include care type, listed services, a phor.me page, and an appointment-request link. It also explicitly states what the tool does not do: diagnose, treat, show prices, or book.

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

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

The description is front-loaded with the primary use case, then adds return behavior and guardrails in a compact sequence. Although it is detailed, every clause contributes useful selection or invocation context.

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?

The definition is complete for a two-parameter, optional-input, read-only search tool: it explains when to use it, how location is resolved, what is returned, and what it must not be used for. An output schema exists, so the description need not fully document the return shape.

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

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

With 100% schema description coverage, the schema already documents both parameters, so the baseline is 3. The description adds useful semantic guidance: it takes a place and a kind of care, never symptoms, and clarifies that when no city is named it uses the approximate location shared by the assistant.

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 finds in-person clinic/recovery partners for a user-named city or approximate location, and distinguishes the resource from symptoms, diagnosis, treatment, and booking. It does not explicitly name a sibling tool alternative, so it is clear but lacks the explicit sibling differentiation that would warrant 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?

It gives a strong when-to-use condition: the user wants to be seen in person by a physical therapist, sports medicine clinic, chiropractor, sports massage therapist, or recovery studio. It also includes boundaries such as 'never symptoms', no diagnosis/treatment, no prices, and no booking, but it does not name the alternative sibling tools to use for those excluded actions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces with 'reads only and changes nothing'. Beyond that it discloses return cardinality and ordering ('up to three brains that fit, best first'), the fields returned, and that a code narrows to exactly one brain plus its page. It doesn't cover the zero-result case, which would fully close the loop.

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 triggering condition and examples before the definition, then behavior, then exclusions. Dense but every sentence carries routing or behavioral information; the definition sentence is slightly long but earns its place by disambiguating 'brain'.

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 five optional parameters, rich annotations and an output schema, the description covers usage modes, return shape and scope exclusions, so an agent can call it correctly. The only gap is behavior on no-match results, a minor omission given the 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 coverage is 100%, so the schema alone earns a baseline 3. The description adds genuine conditional semantics the schema cannot express: goal is 'needed unless a code is given', coach filters to that coach only, and sport/days_per_week should only be supplied if the user said so, which constrains opportunistic parameter filling.

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 (find) and resource (Phorme coaching brain), then defines the resource concretely as 'a coach, the principles the method trains by, and a coach-built programme'. Concrete example utterances and the sibling-ish alternatives (named coach, coach code) make it distinguishable from search_phorme_programs and find_personal_coach.

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 triggers with user-voice examples, plus three mode variants (goal, named coach, code). It also states when NOT to use it: 'Do not use it for injury rehab or nutrition', and implies the pre-condition that the user hasn't picked a programme yet.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint false, openWorld false), yet the description adds real behavioral detail: it returns at most five library movements, each with a demo link, and it discloses the fallback behavior of offering the nearest kind when no exact match exists. The read-only claim is also scoped concretely ('changes nothing, including any saved plan').

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

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

Three sentences, front-loaded with the usage trigger, then return behavior, then the safety and exclusion clauses. No sentence is redundant and the most decision-relevant content (when to call, when not to) comes first.

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?

Despite an output schema existing, the description still summarizes the return shape (up to five movements, demo links, nearest-kind fallback), and covers triggers, safety, and the injury exclusion. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the 'as the user wrote it' phrasing and the ["none"] equipment example. The description reinforces how available_equipment drives the result set but adds no syntax, format, or handling detail beyond the schema, and never mentions the 'reason' enum. Baseline 3.

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

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

States a specific verb and resource ('find a replacement for one exercise') plus the three concrete triggers (no equipment, station taken, wants a different option). This is unmistakably distinct from every sibling (get_*, save_*, preview_*, search_*), none of which substitutes an exercise.

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

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

Explicit when-to-use conditions are given with a worked example ('no cable machine for cable rows'), and an explicit when-not is provided ('Do not use it to work around pain or injury'). No sibling tool offers an alternative path here, so the absence of a named alternative is not a gap.

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

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

Despite annotations already covering the read-only safety profile, the description adds substantial behaviour: a cap of five results, nearest-or-best-match ordering, the per-result payload (page link, class id, local start time, length, places left, booking link), the no-match fallback to further-out places plus a coaching-brain home plan, and the explicit note that no prices are shown. These are traits an agent could not infer from the annotations.

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

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

Front-loaded correctly with the trigger sentence before the return-value detail, and no filler. It is one long run-on paragraph however, and the return-format middle clause could be split for easier scanning.

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 four-parameter, zero-required search tool with an output schema, this covers everything an agent needs: when to call it, how location resolution works, result ordering and count, what each result contains, and what happens on empty results. Return-value detail is redundant with the output schema but harmless.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: city being optional and falling back to a 60 km (or radius_km) search around a shared location, and that it looks at classes "in the coming days" matching the days parameter. Only class_type and the exact days default are left to the schema, so it improves on baseline without being exhaustive.

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

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

States a specific verb and resource (find gyms, studios and classes to train at in person) and immediately scopes it to the in-person training case with concrete example queries. An agent can distinguish this from find_clinic, find_personal_coach, find_races or book_gym_class without inspecting any schema.

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

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

Opens with an explicit trigger ("Use this when the user wants a gym, studio or class to train at in person") that matches sibling tools' territory. It also draws the boundary against the booking flow ("booking a class for a signed-in user is a separate step"), routing that need to book_gym_class, and explains the fallback when no city is named.

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

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

Annotations already declare readOnly=true, destructive=false and openWorld=false, so the safety profile is covered; the description adds genuinely new context by stating the tool shows no prices, books nothing and changes nothing, and that coaching is training not medical care. It stops short of describing limits like result caps or ranking, which is minor given the annotation coverage.

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 one long run-on sentence, but it is front-loaded with the trigger and every clause (what it returns, what it does not do, scope disclaimer) carries information. Slightly dense but no filler.

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

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

An output schema exists, so the return-value enumeration is partly redundant, yet the description supplies the non-obvious domain boundaries (no prices, no booking, not medical care) that structured fields cannot express. Sufficient for an agent 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 description coverage is 100% with only two optional params, so the schema already carries the semantics; the description only indirectly illustrates them via the example utterances. Baseline 3 is appropriate since no additional syntax or format detail is added.

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

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

States a specific verb and resource ('find' + 'personal/human coach') and immediately scopes it as 1:1, program-writing, weekly-check-in coaching, which distinguishes it from siblings like find_coaching_brain or find_clinic 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?

Trigger conditions are explicit and illustrated with realistic user phrasings ('I want a real coach for basketball', 'can someone coach me one on one?'). It gives no negative guidance naming an alternative tool (e.g. when to use find_coaching_brain instead), so it falls short of a full when/when-not/alternatives treatment.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description reinforces with 'It reads only and changes nothing.' It adds genuinely non-obvious context: data provenance ('verified race listings'), a freshness caveat ('as the organiser last showed it'), and a coverage limit ('Only races in Phorme's listings are returned').

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

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

Front-loaded with the trigger sentence and efficiently sized overall. The middle sentence is long and enumerates returned fields (city, date, page, registration, plan, logistics) that an output schema already carries, which is minor redundancy but not damaging.

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

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

With an output schema present, the description needn't explain return values, and it still covers search scope, data source, freshness and the boundary that only Phorme-listed races are returned. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents kind, where, from_month and to_month with examples, patterns and 'leave out for any/anywhere' semantics. The description mainly restates this and adds only a mild nuance about months being filtered 'by date only', so it stays at the high-coverage baseline.

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

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

States a specific verb (lists/finds races) and resource (Phorme's verified race listings), and scopes exactly what it filters on: kind of race, place, and months. It is clearly distinct from siblings like plan_for_race or find_clinic, so an agent can route correctly 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?

Opens with an explicit trigger ('Use this when the user is looking for a race to enter') backed by three concrete user-style examples that map to the parameters. It gives strong positive guidance but never states when-not to use it or names a sibling (e.g., plan_for_race) as the alternative once a race is chosen.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description still adds value by stating the return is a link only, that nothing is paid or changed in chat, and that a connected Phorme account is required. This adds prerequisite/auth context beyond the annotations.

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

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

The trigger condition is front-loaded and the sentences are short and purposeful. The clause 'nothing is paid or changed in the chat, and it changes nothing by itself' restates the same reassurance twice, a minor redundancy.

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

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

With an output schema present, the description need not detail the return payload, and it still usefully explains the link nature of the result plus the connected-account requirement. It covers trigger, behavior and prerequisite adequately for a zero-parameter 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?

The tool takes zero parameters and the schema coverage is 100%, so per the baseline rule a 4 is appropriate. There is no parameter detail the description could meaningfully add.

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

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

The description states a specific verb and resource: it returns a Stripe billing link for an owner on the gym plan. It is clearly distinguishable from a generic billing tool and from the sibling get_payout_setup_link by naming the audience and the destination page.

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

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

It gives explicit trigger conditions ('when an owner on the gym plan wants to change the card, see invoices or change how many places the plan covers'), which is strong when-to-use guidance. It does not explicitly name or contrast an alternative sibling tool, so it falls short of a 5.

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

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

Beyond the readOnly/openWorld annotations, it discloses a real auth prerequisite ('needs a connected Phorme account') and a data-gating behavior: free listings return only a little reach and what was missed, with the rest locked like the web console. That tier behavior materially affects how an agent should interpret results. The 'reads only and changes nothing' line is largely redundant with readOnlyHint=true.

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 trigger condition is front-loaded, followed by return contents and then the free-tier caveat and auth note. It is a bit dense in the middle where it enumerates many metrics, but every clause carries information an agent can act on.

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

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

An output schema already exists, yet the description still conveys the access-gating and auth requirements an agent needs to set expectations. Combined with the annotations, nothing essential is missing for a zero-parameter 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. The description correctly indicates the report is implicitly scoped to the connected account rather than requiring any 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 specific verb and resource — it returns each place the connected account lists, with page, status, and a report of metrics. It also scopes the audience ('gym, studio or clinic owner... their own places on Phorme'), which separates it from the coaching-oriented sibling get_my_coaching_business.

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

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

It gives explicit trigger conditions and two example user utterances ('how is my gym doing on Phorme?', 'did anyone book this week?'), making the use case easy to match. It stops short of naming a specific alternative tool or stating when not to use it, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context beyond annotations: it needs a connected Phorme account, weights are in pounds, it emits a chart card, and it lists logged lifts on no match. Does not discuss rate limits or pagination, but coverage is strong for a read-only tool.

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

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

A single dense paragraph, front-loaded with the trigger condition. Every sentence carries information; minor density but no waste.

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

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

With an output schema present, the description needn't detail return values, and it still gives account prerequisite, unit system, chart card behavior, and empty-match fallback. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including the months default. The description reinforces the movement matching behavior (finds by the words the user uses) but does not add syntax or format beyond the schema. Baseline 3 is right.

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 (chart/find) and resource (lift progress) and distinguishes itself from siblings like get_training_history and get_planned_sessions by returning per-session data points plus a chart. The description makes clear what it returns (one point per session with best set, estimated max, volume) so an agent can pick 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 explicit user-phrasing triggers ("how is my bench going", "chart my squat over six months") and the condition for the no-match fallback. Practical routing guidance beyond mere purpose.

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?

Explains a non-obvious behavior that the annotations alone only hint at: the code is lazily generated on first request and then persists as the brain changes, which justifies readOnlyHint=false and idempotentHint=true. It also discloses the authorization prerequisite (a connected Phorme account that owns the brain) and what the code does downstream (grants a starting copy of that brain).

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 trigger condition ("Use this when..."), followed by mechanism, effect, and prerequisite in four tight sentences. Nothing is redundant, though the clause about the code being made on first request and kept is slightly clunky in phrasing.

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 tool with an output schema, the description covers the trigger, the side effect of first-use generation, the auth requirement, and the real-world consequence of sharing the code. An agent has everything needed to call it correctly without further inference.

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

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

Schema coverage is 100% and the single brain_id parameter is fully documented, so the schema carries the load. The description only implies that brain_id selects among the coach's brains ("one of their coaching brains") without adding format or sourcing detail beyond that.

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

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

States a specific verb and resource: retrieve the shareable code/link for one of the coach's own coaching brains, with a concrete example code format (K7Q2-XR4D). It is distinguishable from siblings like find_coaching_brain (search) and copy_coach_from_code (import), though it never names those alternatives 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 an explicit trigger with a quoted user utterance ("what is my coach code?"), which makes the intended invocation context unmistakable. It stops short of stating when not to use it or which sibling to pick instead (e.g., copy_coach_from_code for someone else's code).

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

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

Adds value beyond annotations: 'reads only and changes nothing' reinforces readOnlyHint, and it discloses the account prerequisite plus the specific fallback behavior ('an account without a coaching brain gets the address of the coach console'). It doesn't mention rate limits or output format, but the output schema covers 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, each earning its place: first the trigger and scope, then the safety and account requirements. Front-loaded with the use case.

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

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

For a zero-param read tool with an output schema, it covers the trigger, safety profile, account precondition, and fallback behavior. Nothing an agent needs to call it correctly is missing.

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

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

Zero parameters, so the baseline is 4. The description correctly implies no inputs are needed and focuses on what the call returns and its account prerequisites.

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 my coaching brains') and enumerates what it returns: member counts, who went quiet, earnings, and note-sendability. This distinguishes it from siblings like find_coaching_brain (search) and send_note_to_my_members (write).

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

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

Opens with 'Use this when a Phorme coach asks about their own coaching brains', clearly framing the trigger condition. It doesn't explicitly name alternatives like find_coaching_brain, but the 'own' framing and read-only nature differentiate it adequately.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered; 'It reads only and changes nothing' largely restates that. The description does add non-annotation context: the auth requirement ('needs a connected Phorme account') and the shape of the returned ledger (earned, paid out, going out, owed now, bank setup, recent payouts).

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

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

Four sentences, front-loaded with the trigger scenario, then returns, then safety, then prerequisite; each sentence is short and readable. It loses a point for mild redundancy, since 'reads only and changes nothing' duplicates the readOnlyHint/destructiveHint 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 inputs and an output schema present, the description only needs the trigger, the read-only nature and the account prerequisite, and it supplies all three. Return-field detail is covered by the output schema, so no agent-facing gap remains.

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

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

The tool takes zero parameters (empty object schema, additionalProperties=false), so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter meaning is 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?

Names a specific verb+resource+scope ('what Phorme paid them', earned/paid/owed ledger for the account) and anchors it with a concrete user utterance ('what did Phorme pay my gym?'), which separates it from the reporting sibling get_gym_report and the link-generating get_payout_setup_link. An agent can identify the tool without opening the schema.

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

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

Gives an explicit trigger ('Use this when an owner asks what Phorme paid them, or what goes out next') plus the prerequisite of a connected Phorme account. It does not name a specific alternative to use instead, e.g. get_gym_report or get_payout_setup_link, so exclusion guidance is absent.

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

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

Goes well beyond the annotations (readOnly=false, openWorld=true, idempotent=true, destructive=false) by disclosing the data flow and safety posture: it returns a link to Stripe's own form, the bank is never given in the chat, and it takes no payment. The connected-account prerequisite is an operational constraint the annotations do not convey.

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

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

Four tight sentences, front-loaded with the triggering situation before the mechanics and constraints. Slight redundancy between 'has not set it up' and 'no bank is set up yet' costs a point but nothing is wasted overall.

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 only two parameters at full schema coverage, an output schema, and rich annotations, the description supplies everything else an agent needs: precondition, consent workflow, third-party handoff, and what the tool does not do (no payment, no bank details in chat). Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics for 'confirmation' by framing it as a consent gate that must only be true after the owner agrees. The 'country' parameter is left entirely to the schema (which already supplies format and default).

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 (return a setup link for owner bank payouts) plus the exact situation that triggers it: the owner wants their share paid to their bank and has not set it up. This distinguishes it cleanly from the adjacent 'get_payouts' listing tool without the agent needing to open 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 an explicit when-to-use condition ('has not set it up, for example when no bank is set up yet'), a required conversational workflow ('confirm with the owner first, set confirmation to true only after they said yes'), and a prerequisite ('needs a connected Phorme account'). The unset-bank condition effectively excludes the already-configured case.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds domain-specific guarantees beyond that ('shows no prices and starts no purchase') and lists what is returned, which is genuinely useful value.

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

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

Three tight sentences, front-loaded with the usage condition, then the return contents, then the behavioral guarantee. No filler and no repetition.

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

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

An output schema exists, so return details need not be exhaustively specified, yet the description still summarizes them. For a single-parameter read tool with full annotation coverage, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and there is one required parameter whose schema text already explains its origin ('The program id returned by search_phorme_programs'). The description adds no further syntax or format detail, so the baseline of 3 applies.

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

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

States a specific verb (returns/reveals) and resource (a single Phorme program), and the clause 'when the user picked one Phorme program' sets it apart from the browsing sibling search_phorme_programs. 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?

The opening clause gives explicit when-to-use context ('when the user picked one Phorme program and wants its details'), and the parameter notes the id comes from search_phorme_programs. It stops short of explicitly naming when NOT to use it or spelling out the alternative as a routing 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?

Annotations already declare readOnlyHint and destructiveHint, so 'reads only and changes nothing' is partly redundant. However, the description adds genuinely useful context the annotations do not carry: the connected-account prerequisite and the pounds unit for weights.

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 usage trigger and example, then the return contents and constraints. Four sentences with little waste, though the read-only statement partly overlaps the annotations.

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

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

An output schema exists so return values need not be explained. The description covers the auth requirement, unit system, and safety profile, leaving little for an agent to guess, though it does not describe how sessions are ordered or scoped.

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

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

Schema description coverage is 100%, so the single 'days' parameter is already fully documented with its default and range. The description's mention of 'today or the coming days' adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (get planned sessions) with a concrete example ('what is my workout today'). It is clearly distinguishable from siblings like get_training_history (past) and get_saved_training.

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 frames when to use it ('when the user asks what their Phorme plan has for today or the coming days') with a sample query. It implies but does not name an alternative for historical data, so it stops short of the when-not/alternatives tier.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the read-only profile is largely free. The description still adds useful context beyond them: the result is scoped to training 'owned by the connected Phorme account' and the operation 'changes nothing', which tells the agent about account scoping and side-effect freedom. It stops short of disclosing failure modes (e.g. what happens if the id belongs to another account or was never saved).

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

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

Four short sentences, each doing distinct work: trigger, return payload, required input, and negative scope. The usage condition is front-loaded and there is no filler or restatement of the title.

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

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

With annotations covering safety, a fully described 2-parameter schema, and an output schema that carries return detail, the description fills every remaining gap: when to call it, what it is scoped to, and what it refuses to do. An agent has everything needed to select and 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 description coverage is 100% and both parameters are already documented, including the provenance of training_id from the save tools and the workout/program enum. The description only restates that training_id is 'from that save', adding no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('get... training already saved to Phorme') and pins the return payload ('title and open link'), which separates it from save_workout_to_phorme, save_program_to_phorme, and search_phorme_programs. The closing sentence explicitly disclaims the neighbouring behaviours (list, search, edit, delete), so an agent can route correctly without opening another schema.

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

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

It gives an explicit trigger ('when the user asks about a workout or program already saved to Phorme in this conversation, for example to get its Phorme link again') and an explicit set of exclusions in the same breath. Nothing about when-not-to-use is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered and 'it reads only and changes nothing' is largely redundant. The description does add non-annotation context: a connected Phorme account is required, and weights are returned in pounds. That is meaningful added behavior for a data-returning tool.

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

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

Front-loaded with the usage trigger, then what it returns, then constraints, then units – a sensible ordering with no wasted framing. Two clauses are redundant against structured data ('it reads only and changes nothing' vs. readOnlyHint; the full return enumeration vs. the existing output schema), which keeps it just short of a 5.

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

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

For a single-optional-param read tool with an output schema, the agent has everything it needs: when to invoke it, what data domain it covers, the account prerequisite, and the unit convention. Return-shape detail is arguably unnecessary given the output schema, but its presence costs nothing and nothing required is missing.

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

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

There is a single optional 'limit' parameter and schema description coverage is 100%, so the schema already fully documents count semantics, default of 10, and the 1-20 range. The description only implies newest-first ordering via 'most recent logged workouts' and adds no syntax or formatting detail beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description names a specific verb+resource (their own logged training in Phorme) and enumerates exactly what comes back: recent workouts with sets, best set, estimated max, volume, 7/30-day workout counts, and latest records. That level of detail makes it distinguishable from siblings like get_lift_progress (trend analysis), get_planned_sessions (future sessions), and get_saved_training (saved items) without opening any schema.

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

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

It gives explicit trigger phrases – 'what they did last time', 'how often they trained', 'personal records', 'a next workout built on their recent sessions' – and scopes usage to the user's own data. It stops short of naming alternatives or stating when NOT to use it (e.g., for progress trends use get_lift_progress, for upcoming sessions use get_planned_sessions), so it is clear context without exclusions.

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

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

Annotations already declare read-only/non-destructive/open-world=false, so safety is covered; the description adds real domain behavior beyond that: the 7-day hold for class bookings and 1:1 requests at non-gym-plan places, expiry timing, accept-now eligibility, and the auth prerequisite (connected Phorme account that owns the place).

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

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

Front-loaded with the use-case trigger in the first sentence, followed by policy, payload, safety, and auth in a compact block. Every sentence carries information, though the return-field enumeration is somewhat list-heavy given an output schema exists.

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

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

With an output schema present, the description need not detail return values, and it still supplies the business rule (7-day hold), auth requirement, and safety profile an agent needs. The only gap is that it never echoes the place_id default behavior, which the schema already covers.

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

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

Schema description coverage is 100% on the single place_id parameter and its 'leave out for all places' semantics, so the baseline is 3. The description alludes to 'the place' and non-gym-plan places but adds no parameter-level syntax or default information 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 and resource in owner-facing terms ('list asks waiting for my gym' / 'who wants to book or visit their place'), so an agent can tell it is the read-side counterpart to answer_held_request. The example query (

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

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

Gives an explicit trigger condition (an owner asks who wants to book or visit) plus a natural-language example phrasing. It does not name the sibling action tool (answer_held_request) or state an exclusion, so it stops short of 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/destructiveHint=false and openWorldHint=false, and the description reinforces that ('reads only and changes nothing'), but it also adds genuinely non-structural behavior: it discloses refusal semantics ('If the race is not listed it says so; never guess a race date') and the provenance of race logistics (page and date they were read). The one gap is that most of the returned-content detail duplicates the output schema.

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

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

The critical usage trigger is correctly front-loaded, but the single ~200-word paragraph for a one-parameter tool carries redundancy: the enumeration of sets/reps/paces/coach-notes/demo-link return values overlaps the output schema, and 'reads only and changes nothing' repeats the readOnlyHint annotation. Several sentences could be trimmed without losing callable 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?

Given a single string parameter, full annotation coverage and an output schema, the description supplies everything else an agent needs: the trigger, the triathlon-vs-single-sport scope (swim/bike/run in one plan for IRONMAN 70.3/5150/full), the not-listed failure path, and what data comes back inclusive of race logistics provenance.

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 required parameter and 100% schema description coverage, the baseline is 3, but the description adds real semantics by showing three colloquial, possibly fuzzy namings ('IRONMAN 70.3 Barranquilla', 'I signed up for the half ironman in Cartagena', 'Chicago Marathon'), telling the agent that free-form user phrasing is expected and resolved against the listings.

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 action chain (find the race in Phorme's listings, count weeks to race day, return the matching plan week) rather than restating the title. An agent can distinguish it from siblings like find_races or get_phorme_program without opening any schema, because it states it produces a training plan keyed to a race date.

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

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

It gives a clear trigger condition (the user names a race they are training for) with three concrete utterance examples, plus explicit exclusions ('Do not use it for injury rehab or nutrition'). It stops short of naming which sibling to use instead for those excluded cases, so it is clear context rather than full when/when-not/alternative routing.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false, which leaves the write semantics ambiguous. The description resolves this: it stores a private 24-hour preview, does not persist to any account, and performs exercise-library matching — exactly the behavioral traits an agent needs before invoking.

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

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

Four short sentences, each load-bearing: trigger, mechanics, persistence guarantee, exclusions. The most decision-relevant information (what it does and what it does not save) 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?

An output schema exists, so return values need no explanation. For a complex nested-input tool with annotations covering only safety hints, the description supplies the missing lifecycle, persistence, and routing 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 100% with one deeply nested, well-annotated parameter, so the schema already carries the parameter burden. The description adds only the provenance constraint that the program comes from the current conversation; no field-level meaning is added. Baseline 3.

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

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

States a specific verb (preview) and resource (a multiweek training program from this conversation) and describes the concrete steps taken: checking every week and workout, matching exercises to the Phorme movement library. It explicitly excludes single workouts, cleanly separating it from the sibling preview_workout_import.

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

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

Opens with an explicit trigger ("Use this when the user wants to turn a multiweek training program... into trackable Phorme training") and closes with explicit exclusions ("Do not use it for a single workout, nutrition plans or medical questions"). The alternative for the single-workout case is named by implication.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds a selection heuristic (closest coach-built program) and a fallback behavior (match_quality and limits when no program exists). This goes beyond the annotations, though the 'reads only and changes nothing' statement is largely redundant.

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

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

Four sentences, each serving a distinct purpose: usage trigger, behavior, safety, and exclusions. Front-loaded with the primary use case and no wasted language.

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?

The description covers usage, exclusions, and a failure mode, while annotations handle safety and an output schema covers return structure. Nothing essential for 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 description coverage is 100%, so the schema already documents sport, season_phase, and gym_days_per_week. The description adds no parameter-level syntax or constraints beyond what the schema provides, so the baseline 3 applies.

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

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

States the specific action (plan a sport training week) and resource (one week of gym sessions built from a Phorme sport program), and the 'use this when' clause distinguishes it from race planning and generic program retrieval siblings. The concrete basketball example makes the intent 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?

Provides a clear when-to-use clause and explicit exclusions (injury rehab, children's team practice plans, nutrition). However, it does not name an alternative sibling tool to use instead in the excluded cases, so it falls short of the top score.

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

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

Annotations declare readOnlyHint=false/destructiveHint=false/openWorldHint=false but say nothing about persistence. The description fills that gap: the preview is stored privately for 24 hours and no training is saved to any account, which resolves whether the write is durable. It stops short of stating auth requirements or what happens on expiry, so it lands just under 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?

Four sentences, front-loaded with the selection trigger before the behavior list and the exclusions. The middle sentence is dense with comma-separated clauses but each clause carries distinct operational information, so nothing reads as 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 tool with 4 parameters, a nested workout object, and an output schema (so return values need no prose), the description covers scope, transformations performed, storage lifetime, persistence boundary, and exclusions. An agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining the effect of the optional inputs: it checks for equipment the user did not list and for workouts running past their stated time, which clarifies why time_limit_minutes and available_equipment exist rather than just what they accept.

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 ('preview a single workout in Phorme') and enumerates the concrete work performed: validates the workout, maps exercises to the Phorme movement library with demo links, flags equipment/time conflicts, and stores a private 24-hour preview. This is clearly distinguishable from siblings like save_workout_to_phorme, preview_program_import, and preview_sport_week.

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 triggers (workout written in conversation, pasted from notes, or built to fit time/equipment) and explicit when-not conditions ('Do not use it for multiweek programs, nutrition plans, or pain and injury questions'). The exclusions route the agent away from this tool for adjacent requests, which is exactly what selection guidance should do.

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

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

Adds substantial context beyond the annotations: it requires explicit owner confirmation, reuses the same publish checks as the console, and describes the failure path ('when one fails it says what is left and members see no change') — i.e. partial publishes do not leak to members. That matches the idempotentHint=true / destructiveHint=false annotations without contradicting them.

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

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

Four short sentences ordered by importance: trigger, the confirmation gate, publish behavior/failure semantics, then the account prerequisite. 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?

An output schema exists, so return values need not be described. Everything an agent needs to call this correctly — when to invoke, the mandatory confirmation workflow, what happens on check failure, and the account prerequisite — 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 coverage is 100%, so both parameters are already documented; the baseline would be 3. The description adds real operational meaning on top: it explains that 'confirmation' must reflect a human yes ('Confirm with the owner first, and set confirmation to true only after they said yes'), which the const:true schema alone cannot convey, and ties place_id to the owner's 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?

States a specific verb (publishes) and resource (the place's coaching brain) plus the observable outcome: changes reach members. The granularity — a brain belonging to a specific place — distinguishes it from nearby siblings like publish_place, update_gym_brain and start_gym_brain.

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

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

Gives a concrete trigger ('when an owner wants the changes to their place's coaching brain to reach members, for example after its voice, look or programs changed') and a prerequisite (a connected Phorme account that owns the place). It does not explicitly say when not to publish or name an alternative tool, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, yet the description adds substantial context the annotations cannot: listing is free, it takes no payment, starts no plan, non-gym-plan booking asks are held 7 days, and a connected Phorme account owning the place is required. This is exactly the kind of side-effect and prerequisite detail an agent needs before a mutating call.

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

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

The purpose and confirmation requirement are front-loaded, and most clauses (cost, plan, hold window, prerequisites) carry real information. It is dense and slightly run-on in the back half, but no sentence is wasted.

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

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

With an output schema present, return values need not be explained; the description covers the remaining gaps – cost, auth/account prerequisites, side effects on requests, and confirmation gating – leaving nothing an agent needs to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it defines the email precedence chain (request_email, else the place's own, else the account's) and reinforces the confirmation semantics. The fallback logic is genuinely additive.

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

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

The description opens with a specific verb+resource+scope: putting a place live across phor.me, the app map, and the Phorme connector. This clearly separates it from siblings like unpublish_place, update_place, and create_or_claim_place 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?

It states the trigger ('when an owner wants their place live') and a firm prerequisite ('Confirm with the owner first, and set confirmation to true only after they said yes'). It does not explicitly name an alternative tool (e.g. unpublish_place or update_place) or when NOT to use it, so it stops short of a full 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, destructiveHint=false, openWorldHint=false, and the description is consistent with them ('reads and changes nothing in Phorme'). It goes beyond the annotations by disclosing that the tool is purely presentational — 'displays only the title, counts, status and link it is given' — telling the agent it does no fetching or enrichment, which is the key behavioral fact here.

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

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

Three short sentences, zero filler, with the primary purpose front-loaded and the behavioral caveat last. 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 pure renderer with an output schema present, the description need not explain return values, and it correctly focuses on input expectations and the no-side-effects guarantee. The remaining gap is the four schema parameters with no description anywhere, which leaves an agent guessing at what counts/kind mean.

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 43%, with training_kind, warning_count, exercise_count and estimated_duration_minutes undocumented in the schema. The description partly compensates by naming what is rendered (title, counts, status, link), which maps onto those fields, but it adds no format or unit meaning for the undocumented ones. Baseline 3 for partial 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?

States a specific verb and resource: 'show a compact Phorme card for a workout or program.' The phrase 'that was just previewed or saved' scopes it to post-preview/post-save results, which separates it from preview_workout_import and save_workout_to_phorme without naming them. It is clear what the tool produces, though it never names the siblings it is not.

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

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

'Use this to show a compact Phorme card for a workout or program that was just previewed or saved' gives a clear triggering condition tied to the preview/save flow. It does not spell out alternatives or a when-not case, but the temporal condition is enough for an agent to place it correctly in a sequence.

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 it is a non-destructive write; the description goes further by disclosing that the result is a draft, that members see nothing until the coach adds it in the coach console, and that a connected Phorme account owning the brain is required. These are exactly the behavioral traits annotations cannot express.

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

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

Three tight sentences: the trigger condition comes first, then the write semantics, then the account prerequisite. No filler and nothing 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?

An output schema exists so return values need not be explained, and the description covers the trigger, the resulting state, visibility, and the auth prerequisite. An agent has everything needed to decide and call correctly.

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

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

Schema description coverage is 80%, so most parameters (weeks, brain_id, sessions, reps, rest, seconds, confirmation) are already documented in the schema. The description only restates the kind of content saved and adds no format or constraint detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource ('saves the program as a draft on that brain') plus the content captured (session names, exercises, sets and reps). It is clearly separable from the adjacent save_program_to_phorme sibling by targeting the coach's coaching brain rather than Phorme directly.

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

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

Gives an explicit trigger condition: the coach wrote a program in this conversation and clearly asked to save it to a coaching brain. It does not name save_program_to_phorme as the alternative or state when not to use this tool, so the routing between the two save tools is only implied.

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

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

Adds substantial context beyond annotations: requires connected Phorme account with training:write permission and a membership including programs; returns a link; failure mode when membership is missing; no purchase is initiated; idempotency semantics with idempotency_key. Annotations declare idempotentHint=true, and the description explains how to achieve it. No contradictions.

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

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

Front-loads the trigger condition, then lists requirements, failure mode, exclusions, and idempotency. Six sentences with minimal waste, though slightly verbose for a three-parameter tool. Every sentence adds value but could be tightened.

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?

Complete for a write tool: covers preconditions, permissions, failure behavior, exclusions, and idempotency. Output schema exists, so return values need not be explained, though the description mentions returning a link. No gaps for an agent deciding whether and how to call it.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning: preview_id refers to the preview being saved, idempotency_key reuse prevents duplicate copies, and confirmation must only be set after clear user confirmation. Slightly above baseline due to the idempotency explanation, though it largely aligns with schema descriptions.

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

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

States a specific verb (save) and resource (program preview) with explicit scope: saves a preview to the connected Phorme account as a private program. Clearly distinguishes from sibling save_program_to_my_coaching_brain and save_workout_to_phorme by naming the destination and the source object.

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

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

Explicit precondition: 'when the user has seen a program preview and clearly said to save it.' Also states what happens if prerequisites fail ('says so and saves nothing') and an explicit exclusion ('never starts a purchase'). This covers when-to-use, failure behavior, and a boundary condition.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds substantive context: the saved workout is private, a link is returned, a connected Phorme account with training:write permission is required, and idempotent retries return the same workout rather than duplicating it. This is exactly the extra disclosure the annotations cannot carry.

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

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

Four tight sentences with the usage trigger front-loaded, then behavior, then prerequisites, then retry semantics. No filler or restatement of the title.

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

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

Covers trigger, effect, permission prerequisite, idempotency, and outcome; an output schema exists so return values need not be enumerated. Nothing needed to invoke this write tool correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains the retry semantics of idempotency_key ('reuse the same value so no second copy is created') and frames confirmation as gated on explicit user consent. It stops short of 5 since the parameters themselves are already well documented 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 ('saves that preview to the connected Phorme account as a private workout') and scopes it to a previously seen preview, which cleanly separates it from preview_workout_import and save_program_to_phorme. An agent can identify the correct tool without opening the schema.

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

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

Gives an explicit trigger ('when the user has seen a workout preview and clearly said to save it'), establishing both the precondition and the confirmation requirement. It does not name alternative siblings (e.g. preview_workout_import, save_program_to_phorme) as explicit alternatives, so it stops short of 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 establish a safe read-only, closed-world profile, and the description layers on genuinely new behavior: a hard cap of five results, what each result contains (a sample session from week one plus where to find it in the app), that nothing is changed or purchased, and that ranking is by fit rather than commission. These are the kind of traits an agent could not infer from readOnlyHint alone.

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

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

The trigger condition is front-loaded and each sentence carries distinct information (trigger, result count and shape, safety/no-purchase, ranking policy). It is slightly dense at five sentences, with the pricing and commission reassurances bordering on marketing copy, but nothing is redundant.

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

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

An output schema exists, so return structure need not be spelled out, yet the description still previews result content and cardinality. Combined with annotations covering safety and the description covering scope, limits, and ranking, an agent has everything needed to select and call it correctly.

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

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

With 71% schema description coverage, the schema already explains most parameters, and the description only glosses 'their sport or goal' and hints at creator via 'coach-built'. It adds no syntax, format, or filtering-combination guidance beyond what the schema documents, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('search Phorme programs') and gives a concrete example ('a structured volleyball program'). An agent can distinguish it from the singular fetch tool get_phorme_program and from the save_* siblings without opening a schema.

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

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

The opening clause gives an explicit trigger: 'Use this when the user asks for an existing coach-built training program for their sport or goal.' It signals discovery-oriented intent, implicitly contrasting with get_phorme_program, but never names the alternative or states when not to use this tool, so it stops short of a full 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing concrete behavior: delivery as a notification and in each member's coach history, a 400-character cap, no links allowed, a rate limit of one note per brain per day, and an auth prerequisite of a connected account with an active coach plan owning the brain. These are exactly the operational facts an agent cannot 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?

Three sentences with the usage precondition front-loaded, then effect/limits, then account prerequisites. Dense but every clause carries information; the most useful constraint (one per brain per day) is buried at the end of sentence two rather than surfaced earlier.

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

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

An output schema exists, so return values need no explanation, and the description covers the remaining burden for a 3-parameter mutation: trigger condition, audience, side effects, content limits, rate limit, and account/ownership prerequisites. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 67%, and the description meaningfully supplements it: it clarifies that text is sent verbatim ("as they are"), restates the 400-character ceiling, adds the undocumented 'no links' constraint, and reinforces that confirmation means the coach explicitly approved this exact note. Only brain_id gets no semantic elaboration beyond ownership in the prerequisites.

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: it sends a coach's note to every member training under one of their published coaching brains. It further specifies the delivery form (notification plus coach history), which no sibling tool does, so it is unambiguously distinguishable from the save_*/get_* 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 an explicit trigger condition: use it when a coach has written a note and clearly said to send it, and later that the account must own the brain on an active coach plan. It does not name alternative tools for related tasks (e.g. previewing or editing a note) or state when not to send, so it falls just 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?

Goes well beyond annotations by disclosing that an empty send_to routes to the account's own phone/email, that the phone is never shown publicly, and that a connected Phorme account owning the place is required. These are concrete behavioral/auth facts annotations do not carry, though return/error behavior is left to the output schema.

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

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

Front-loaded with the use case, then the parameter semantics, then the workflow and auth note. Dense but each sentence carries distinct information; slightly long, but 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 3-parameter mutation tool with an output schema, the description covers trigger, parameter meaning, consent workflow, privacy, and auth prerequisite. Remaining gaps (reversibility, error cases) are minor and partly covered by annotations and the output schema.

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

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

Schema coverage is already 100%, so 3 is the baseline. The description still adds value the schema does not fully capture: "one at a time" (single-recipient constraint) and the meaning of an empty send_to, plus the confirmation sequencing tied to owner consent.

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: setting where booking/ask notices for a place get sent. The example ("text my bookings to my phone") and the title make the intent unmistakable, and it is clearly distinct from sibling set_owner_email by scoping to booking notices rather than the owner's contact email.

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

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

Gives a clear trigger ("Use this when an owner wants booking and ask notices for a place sent somewhere else") and a required workflow ("Read it back to the owner first, and set confirmation to true only after they said yes"). It does not name alternative tools, so it stops short of full when-not/alternatives guidance.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds real value: a read-back-and-confirm protocol gated on confirmation=true, the irreversibility that a paid class cannot be cancelled, and an account-ownership prerequisite. However it does not say what happens to attendee bookings if a cancel is attempted despite the rule, or whether edits to a booked class are silently restricted to certain 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 the usage trigger, then proceeds through action semantics, confirmation protocol, constraints and auth requirement, with no filler sentences. It is somewhat run-on, packing multiple rules per sentence, but every clause carries operational 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 10-parameter mutation tool with destructive semantics, the description covers the confirmation gate, irreversibility caveats and account prerequisite, and an output schema exists so return values need not be described. Remaining gaps are edge behavior: which fields are editable on a booked class and what error a non-owner or unpaid-account caller receives.

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 80%, so the schema documents most parameters; the description adds meaning mainly for confirmation (must be true only after the owner said yes) and action=list being non-mutating. Editing restrictions implied by 'a class people booked keeps its time, length and price' are not mapped to specific fields, leaving which of title/minutes/capacity/starts_at are locked 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 resource (class schedule) with a clear verb set (see, add, change, cancel) and scopes it to owners editing their own place, which separates it from book_gym_class and find_gym_class. It never names a sibling explicitly, so differentiation is inferred from the owner framing 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?

Opens with an explicit when-to-use trigger ('when an owner wants to...'), explains that action=list is a pure read, and gives the positive/negative conditions: a booked class keeps its time/length/price, and a class members paid for cannot be cancelled here. Payment is redirected away from this tool to Phorme's own payment page.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, and the description meaningfully extends them: it requires a connected Phorme account that owns the place, warns that a place not on the gym plan cannot enable it, notes the result returns plan_url, and clarifies that no payment is taken and members are approved by the place. It stops short of saying what happens to members already covered when the switch is turned off.

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 when-to-use clause is front-loaded and every sentence carries information (prerequisites, consent gate, cap limit, plan_url outcome, payment disclaimer). It is somewhat run-on with several independent clauses, but nothing is redundant filler.

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

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

An output schema exists so return values need not be spelled out, and the description nonetheless flags plan_url. With annotations covering safety and idempotency, the remaining coverage of permissions, consent flow, and plan gating is solid; only the effect on already-covered members when disabling 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 coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: it explains the cap can only be lowered and is bounded at 50, and frames confirmation as a consent gate tied to the owner's explicit yes rather than a bare boolean.

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

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

The description states a concrete verb and resource: it turns member-cover on or off for a place and can lower the covered-member cap. No sibling tool does anything similar (the nearest, get_gym_report and create_or_claim_place, are only referenced as sources of place_id), so an agent can route to it unambiguously.

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

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

It gives a clear trigger (an owner on the gym plan wants to pay for members' memberships in one place, or wants to stop) and a prerequisite gate ('Confirm with the owner first, and set confirmation to true only after they said yes'). It does not name an alternative tool for any overlapping case, but there is no obvious sibling alternative to point at.

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

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

Annotations only say the tool is not read-only, idempotent, and non-destructive; the description adds substantial non-structured behavior: the draft call saves nothing and returns the rules plus uncovered gaps, the save call validates against sample members and reports whether plans still work, and members train by the saved rules starting next session. Auth ownership requirements and the confirmation precondition are also disclosed, which is exactly the extra context annotations cannot carry.

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

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

Front-loaded with the triggering condition, then the two call modes, then the account prerequisite and confirmation guardrail — a sensible order with little filler. It is dense and run-on in places, but nearly every clause conveys either a mode, a side effect, or a safety rule.

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

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

For a 4-parameter, nested-object, non-idempotent-looking write tool, the description covers the trigger, both call modes, side effects, post-save verification, downstream member impact, and auth ownership. Return values are described even though an output schema exists, so nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds mode-dispatch meaning the schema cannot express: 'text' triggers the read-only draft path, 'rules' plus 'confirmation' triggers the save path, and text must come from the coach's words rather than being invented. The nested 'rules' payload (method, voice, banned_phrases, share) is only enumerated inside the schema description, not the function 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: it reads a coach's own words into coaching-brain rules and can save them. The two-mode behavior (draft read-back vs. save) is spelled out, so the agent knows exactly what will happen. It never names the neighboring tools (start_my_coaching_brain, update_gym_brain, save_program_to_my_coaching_brain), so sibling differentiation is left implicit.

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

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

Gives an explicit triggering condition with concrete examples: 'Use this when a Phorme coach describes how they coach...', and states the prerequisite (a connected Phorme account that owns the brain). It also constrains the risky path: set confirmation true only after the coach confirmed the read-back. It does not name when to prefer a different sibling tool instead.

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

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

Annotations already declare mutating-but-idempotent, non-destructive behavior, and the description adds real context beyond that: the value is never shown to members, an empty string clears the setting, notices fall back to the account's own email or phone, and a connected Phorme account is required. It stops short of describing error behavior if confirmation is omitted, but the schema handles 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?

Four tight sentences with no filler, ordered from trigger to interaction rule to edge case to prerequisite. Every sentence carries distinct 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 two-parameter mutation with an output schema and full annotation coverage, the description supplies everything needed: the trigger, the confirmation protocol, the clearing behavior, the privacy constraint, and the account prerequisite.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the 'empty string clears' semantics and the confirmation gate. The description restates rather than extends this, which is the correct baseline of 3 when the schema does the work.

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+resource — setting the owner's email for plan notices — and frames the triggering scenario (owner who signed in by phone). It does not explicitly differentiate itself from similarly adjacent siblings such as set_booking_notices or send_note_to_my_members, but the resource 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?

Explicit when-to-use ('an owner who signed in by phone wants notices...'), an operational procedure (read the email back, set confirmation true only after they said yes), and the clear-state case (empty email clears it). The agent knows both the trigger and the required interaction sequence.

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

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

Beyond the annotations (which only mark it non-read-only, non-destructive, open-world), the description discloses the full side-effect chain — brain creation, a starting program from the library, publishing, and enrolling the place's members — plus the auth prerequisite (a connected Phorme account that owns the place) and the cost model (free on the free listing). It also encodes a consent gate via the confirmation flag.

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 when-to-use clause and the confirmation requirement, then the side effects, then prerequisites. Dense but mostly earning its place; the middle sentence packs several effects into one long clause that is slightly harder to parse.

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

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

For a mutating, multi-effect operation, the description covers trigger, consent gate, side effects, prerequisites and post-state, and an output schema exists so return values need no explanation. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including defaults and the place_id source. The description reinforces the confirmation semantics but adds no new syntax or format detail, which is the expected baseline when the schema does the heavy lifting.

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

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

The description names a concrete verb and resource — it 'makes a brain from the place's name, line and classes' and puts members under it — and describes the observable end state. It is clear, but it never explicitly distinguishes itself from the near-identical sibling start_my_coaching_brain, which the agent could easily confuse with this 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?

It gives a clear trigger ('when an owner wants a coaching brain for their place'), a required pre-step ('Confirm with the owner first'), and notes the result is editable afterwards. It does not state when NOT to use it or name the sibling alternative, so routing is implied rather than 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?

Annotations declare only write/non-destructive/non-open-world; the description goes further by disclosing the lifecycle state (a draft brain), the visibility rule (members see nothing until the coach publishes it in the coach console), and the auth requirement. This is exactly the kind of behavioral context annotations cannot express.

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

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

Four sentences, front-loaded with the trigger condition and followed by the effect, follow-on action, and prerequisite. Every sentence carries information, though the account/prerequisite sentence could be tightened.

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

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

With an output schema present, return values need not be described. The description covers precondition, effect, visibility, and next step, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100% and the schema descriptions already carry the constraints (length limits, 'never invented', confirmation must be true). The description reinforces that name and method come from the coach's own words, but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (creates a draft coaching brain) and scopes it precisely to a coach/trainer turning their own method into a brain. It is clearly distinguishable from siblings like find_coaching_brain (lookup) and save_program_to_my_coaching_brain (saving into an existing brain).

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

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

Explicit trigger conditions are given: use it when the coach has no brain yet or asks for a new one. It also names the downstream follow-on action ('a first program can then be saved to it as a draft') and a hard prerequisite (a connected Phorme account, created by signing in with a phone number).

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