Pirate Skills

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

Goes well beyond the annotations by disclosing the payment lifecycle: the diamond is held immediately, spent only when Ben's calendar confirms (usually within a minute), and returned if the hour is not booked. It also notes the booking carries its own label and can be moved or cancelled before the hour starts, which is exactly the mutation context 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-loads the core action and the payment consequence, and every clause carries information. The parenthetical asides make it slightly dense and run-on, but nothing is padding.

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

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

For a mutating booking tool with no output schema, it covers cost behavior, timing, refund semantics, and post-booking options. What the response contains is only gestured at ('its own label'), leaving the agent to infer the returned object's 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?

Schema coverage is 100%, so the baseline applies. The description reinforces the critical start-passing constraint and the label convention, but it adds little about topic or timeZone beyond what the schema already documents, so it does not materially exceed the schema's own guidance.

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: spending a diamond to book a one-to-one hour with Ben, with scope constrained to an open hour from my_bookings. This clearly separates it from book_intro_call and the event/cohort booking siblings without needing their schemas.

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

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

Gives an explicit prerequisite (the start must come from my_bookings, passed exactly as listed) and names the follow-up alternatives move_booking and cancel_booking with the conditions that select them. It does not explicitly contrast with book_intro_call, which is the main remaining gap.

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

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

Annotations only say it is a non-read-only, non-destructive, non-idempotent, closed-world write; the description adds the substantive behavior: no charge, calendar invite originates from cal.com, and exactly one upcoming free call per person, after which the call refuses and names the existing booking. It also discloses the answer's return shape (own label and join link) and the follow-up tools for moving or cancelling.

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 action and the constraint on the start value, then the eligibility rules, then the one-call limit. It is dense and slightly repetitive ('free 30-minute intro call with Ben' appears three times), but nearly every clause constrains behavior rather than padding.

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

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

With no output schema, the description still tells the agent what comes back (a booking with its own label and join link) and what to do next. Combined with the eligibility rules, the refusal condition, and the exact-time requirement, an agent has everything needed to call it and handle its failure modes.

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 all three parameters. The description nonetheless adds genuine meaning for 'start' – pass it exactly as listed and refer to the time by its label rather than a computed weekday – which prevents a real class of errors. It says nothing extra about topic or timeZone beyond the schema's Berlin 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 ('Book the signed-in person a free 30-minute intro call with Ben') and pins the source of valid times to my_bookings/introCall.openTimes. It separates itself from the paid sibling book_hour_with_ben by declaring 'No diamond, nothing charged', so an agent can pick the right tool without opening either schema.

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

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

Gives explicit when-to-use ('interested in the Pirate Forge (the Forge Pass) or in working with Ben one to one – Captain on Deck') and explicit when-not ('Never offer it for the Pirate Pass or for an event ticket'). It also routes around alternatives: use this instead of a booking page unless it refuses or fails, and hand off to move_booking/cancel_booking afterwards.

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 past the annotations (destructiveHint true) by disclosing the actual side effect — the diamond is returned to the wallet — plus ownership scoping, the state precondition (upcoming, not begun), and the refusal-with-reason failure modes. This is exactly the behavioral context an agent needs before invoking a destructive mutation.

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 action, with no repeated boilerplate. The closing instruction about naming the booking by label is behaviorally useful rather than filler, though the domain-specific flourish makes it slightly denser than strictly needed.

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 no output schema, the description covers the side effect, eligibility, refusal cases, and the confirm-by-label interaction pattern. Nothing an agent needs in order to call it correctly or to explain the outcome 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 both parameters are already documented, and the schema's bookingId text mirrors the description's provenance note. The description adds no syntax, format, or constraint details beyond what the schema states, so 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 precise verb and resource — cancel one of the signed-in person's own upcoming bookings, by id obtained from my_bookings. The scope qualifiers (own, upcoming, canCancel true, the specific bookable types) cleanly separate it from cancel_registration and the booking-creation 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 explicit eligibility (must come from my_bookings where canCancel is true) and explicit refusal conditions (not theirs, already cancelled, already begun), which is strong when-to-use guidance. It never names the alternative sibling (e.g., move_booking) for a person who wants to reschedule instead of cancel, so it falls short of the top band.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the operation is scoped to the signed-in user and restricted to their own registration, implying an authentication requirement and an ownership check. It still does not say whether the cancellation is reversible or what a repeated call does.

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

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

A single front-loaded sentence with no filler. The scope qualifier and the identifying parameter are both packed into one clause without redundancy.

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

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

For a one-parameter destructive tool with no output schema, the description covers who (signed-in user), what (registration), and which (event id). It is nearly complete; the only gap is outcome behavior such as refunds or confirmation, which the destructiveHint annotation partially offsets.

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

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

Schema description coverage is 0%, so the description carries the burden, and it only loosely clarifies that the id identifies the event ('for an event by its id') — information already implied by the parameter name eventId. No format, source, or example for the id is given, so it adds marginal value over 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 (cancel), a specific resource (registration for an event), and the scope ('signed-in person's own'), which naturally separates it from the sibling cancel_booking. It does not explicitly name the alternative, so it falls just short of a 5.

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

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

Usage is implied by the ownership qualifier ('signed-in person's own registration'), letting an agent infer this is for self-service cancellation. There is no explicit statement of when to prefer this over cancel_booking, no prerequisites, and no note on what happens after cancellation.

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

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

With readOnlyHint=false and destructiveHint=false already declared, the description still adds real value: no card is ever charged by the agent, nothing is charged until the person completes Stripe's page, refused quantity/currency combinations are stated, and credit goes to the initiating agent. The notable gap is idempotency – idempotentHint=false, yet the description never says whether calling twice yields two checkout links or how long a link lives.

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 return value are front-loaded in the opening clause, and each subsequent sentence covers a distinct decision (quantity, currency, exclusions, payment flow). It runs long as a single block and the two currency sentences partially overlap, but little is genuinely 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?

There is no output schema, so the description must describe the return value and does ('a Stripe checkout link'). Combined with the exclusions, refusal rules, and the human-pays-on-Stripe model, an agent has everything needed to call this correctly and set user expectations.

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 offerKey has no schema-level description at all, so the description carries that weight by pointing to get_offers as the source of the key. It also adds semantics beyond the schema for quantity (one diamond per session, other offers refused) and explains currency matching the caller's country, though it stops short of an offer-key format example.

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

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

States a concrete verb and outcome ('Start a purchase ... get back a Stripe checkout link') and enumerates exactly which offers qualify (Pirate Pass, Forge Pass, Captain on Deck, Pirate Forge tier). It explicitly routes away from event tickets and names get_offers/list_events as the related siblings, so an agent can distinguish it without opening schemas.

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

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

Gives both when-to-use (offers from get_offers that are on sale/listed) and when-not (event tickets belong on the event page from list_events). It also spells out the conditional rules for quantity and currency, including the refusal case for quantity on non-session offers.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds substantive behavior: read-live data, only on-sale items appear, retired Forge tiers vanish once passes launch, purchasable=false carries an explanatory note, prices are pre-VAT with a three-month minimum, and payment happens on Stripe's page with no agent handling cards.

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

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

Front-loaded with the core purpose, and most content earns its place, but it is delivered as one sprawling ~300-word sentence with stacked parentheticals and em-dashes that make the routing and pricing rules hard to extract at a glance.

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

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

With no output schema, the description compensates by explaining the returned fields and their quoting meaning, plus the payment flow and the boundary against ticket/free/registration offers. Nothing an agent needs to call or interpret this 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?

Zero input parameters, so the baseline is 4. The description instead documents return-field semantics (priceText as the string to quote with likely-currency-first ordering, and the purchasable flag), which is valuable given no output schema exists.

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

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

Opens with a specific verb+resource+scope: 'What Pirate Skills sells right now, with prices, read live.' It then enumerates the exact offer types (Pirate Pass, Forge Pass, Captain on Deck) and names the sibling that performs the purchase (create_checkout), so the agent can distinguish it from every other tool in the list 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?

Explicit routing in both directions: use this for passes/sessions that 'create_checkout sells', but event tickets come from list_events on the event page, free events via register_for_event, and the free Codex via search_knowledge. The when-not conditions are stated, not implied.

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

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

Annotations already declare this is a non-idempotent, non-destructive write in a closed world. The description goes beyond that by disclosing the eligibility gate (active Forge access), that past sessions are silently skipped, and that the result distinguishes an automatic calendar invite from a manual add by Ben.

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

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

Two tight sentences: the action and its phase/quarter inputs come first, then the constraints, then the return semantics. Every clause carries information and nothing is padding.

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

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

With no output schema, the description carries the return-value burden and does so by explaining that the answer reports whether the calendar invite was sent or Ben adds it manually. Combined with the eligibility and filtering details, an agent has everything needed 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 already 100% with the phase enum documented, so the baseline is 3. The description adds real meaning by clarifying that phase="all" means the whole cohort from now on, which sharpens the temporal semantics of the choice.

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: joining the signed-in person to Pirate Forge live sessions, with the scope parameterized by phase. An agent can distinguish this from register_for_event, book_hour_with_ben, and my_forge_sessions 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 routes the agent to my_forge_sessions as the source of the quarter key and states the eligibility precondition (active Forge access) and the temporal filter (only future sessions are added). No explicit when-not or alternative named, but the context is clear enough to select correctly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is met; the description adds real domain behavior beyond that — Forge cohorts surface only as their first session, weekly sessions are never listed, and registration status appears only for signed-in users. These are non-obvious output traits an agent would otherwise guess wrong.

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

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

Purpose is front-loaded, and with no output schema some return-field explanation earns its place. However, the single sprawling paragraph mixes list semantics with per-field prose and meta-instructions ('the Captain's copy leaves them out'), which makes it harder to scan than it needs to 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 no output schema, the description usefully documents the returned fields (`about`, `cadence`, `when`, `startsAt`/`endsAt`, link, registration flag) and ordering, which is the bulk of what an agent needs. It omits input-side details (type, limit) and any pagination/truncation behavior, keeping it short of complete.

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

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

Schema coverage is only 50% (limit is undocumented), and the description compensates not at all for inputs — it discusses output fields (`about`, `cadence`, `when`, `startsAt`/`endsAt`) and never explains the `type` filter or `limit`. The parameters are simple enough that the gap is survivable, but the description adds no input-side meaning.

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

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

The opening clause names a specific verb+resource+scope (upcoming Pirate Skills events, soonest first by date) and adds return-shape detail (a link per event, registration status for signed-in users). It also explicitly distinguishes itself from the sibling my_forge_sessions for cohort/session questions, so an agent can route 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?

It gives an explicit alternative and the condition that selects it ('When the person asks about their own Forge cohort or its sessions, use my_forge_sessions instead'), plus a scoping rule that Forge cohorts appear only as their start. It lacks broader when/when-not guidance (e.g. vs get_offers or register_for_event), so it falls 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 only declare readOnly=false, destructive=false, idempotent=false, openWorld=false; the description goes far beyond by disclosing side effects (nothing charged, the hour keeps its diamond, the call stays free, the calendar sends an updated invite) and precise refusal reasons (not theirs, cancelled, begun, awaiting calendar, time not open). That is exactly the behavioral context an agent needs before invoking a non-idempotent mutation.

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?

Dense but front-loaded: the operation and its scope come first, then the time-source branching, then side effects, then failure cases. It is a single long paragraph with some run-on nesting (parenthetical id conditions, dual time sources), though almost every clause carries unique 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 non-idempotent mutation with no output schema, the description covers purpose, valid inputs per booking kind, side effects, and the full failure surface, and it describes the response shape ('the answer's booking has the new label'). Little an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the start/bookingId descriptions already say 'exactly as my_bookings lists it', so the description largely reinforces the schema. It does add genuinely new constraints: pass the start exactly as listed, and refer to the new time by its label rather than a self-computed weekday, which goes beyond the schema text.

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 (move one of the signed-in person's own upcoming bookings) plus the exact target (another open time of the same kind). It implicitly separates this from book_hour_with_ben / book_intro_call (creating new bookings) and cancel_booking, and names my_bookings as the source of ids.

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

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

Explicitly says when this applies (bookings from my_bookings where canMove is true) and gives the branch-specific alternative sources of valid start times: openHours for an hour with Ben, introCall.moveTimes for the free intro call. It also enumerates the conditions under which the call is refused, which functions as when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the bar is low. The description still adds value by disclosing the shape of the returned data — access categories plus when and how each was unlocked — which 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?

A single sentence that front-loads the resource and then lists its scope. No filler, no restatement of the tool name.

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

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

With no output schema, the description carries the burden of describing results, and it does so at a high level (categories and unlock provenance). For a zero-parameter read tool that is nearly sufficient; a note on result ordering or whether access is workspace-scoped would close the gap.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description is needed to disambiguate arguments, and nothing misleads about how the call is made.

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

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

States a specific resource (the signed-in person's access/entitlements) and enumerates its scope: the Codex, event series, the Forge, tools. That enumeration implicitly separates it from my_bookings, my_wallet and my_profile, though no sibling is named explicitly.

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

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

Usage is only implied by the 'signed-in person' framing and the 'my_' naming convention. There is no explicit statement of when to reach for this versus my_profile or my_forge_sessions, and no exclusions or prerequisites are given.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), but with no output schema the description must carry return-shape disclosure and it does so in detail: booking fields (`id`, `label`, `canCancel`, `canMove`), open-time structure (`openHours`, `introCall.moveTimes`, `openDays`, `bookableUntil`), and the `url` fallback. It also discloses non-obvious handling rules — quote `label` exactly and never derive a weekday/date from `start`, pass `start` exactly as listed — which are behavioral constraints an agent cannot get from structured fields.

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

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

It is a single dense run-on paragraph that mixes return-value documentation, field semantics, and usage routing without front-loading a purpose statement, so the reader must reconstruct the tool's job from the middle. Nearly every clause carries real content, so it is verbose rather than padded, but it is not structured for fast 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 read-only aggregation tool with no output schema, the description supplies everything an agent needs: what collections are returned (bookings, open hours, intro call), the field names and their meaning, the status vocabulary (held/confirmed/cancelled), day grouping and `bookableUntil`, and the exact time-handling rules. Nothing material about invoking or interpreting the response is omitted.

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 and the schema already documents limit, purpose, and timeZone. The description still adds meaning beyond it: it explains what `timeZone` actually does ('Pass their time zone to get the times in it'), clarifies that `purpose` scopes the booking window ('the next two weeks are listed, and a chat that can show a time picker shows one'), and frames `purpose` as conditional on intent. `limit` is not elaborated beyond the schema.

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

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

The description clearly establishes the resource and scope — the signed-in person's bookings with Ben plus bookable open hours and the free intro call — and names the siblings that mutate state (book_hour_with_ben, book_intro_call, cancel_booking, move_booking), so an agent can separate it from a pure list or a mutating tool. It is weakened only by opening on a noun phrase ('The signed-in person's time with Ben') rather than a leading verb, so the core action is inferred rather than stated up front.

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?

Routing is explicit: cancel via cancel_booking, move via move_booking, book hours with book_hour_with_ben and intros with book_intro_call, with the `url` page reserved as a fallback 'only if booking here fails'. The schema-adjacent instruction 'Pass `purpose` when the person wants to book... Omit when they only ask about their bookings' is a genuine when/when-not rule. No guidance is given on when NOT to call this at all relative to siblings like my_wallet or my_profile, keeping it just under top marks.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuine context beyond them: the returned fields (Build weeks 1-6, Grow weeks 7-12, sessions left, in-status) and the no-access edge case returning empty with hasAccess false.

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

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

A single sentence that front-loads the resource and scope before the return fields and edge case. It is dense but every clause carries information; only the length of the phase-week parenthetical makes it feel slightly run-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?

With no parameters and no output schema, the description correctly compensates by describing the return content and the empty/no-access outcome. Nothing critical for correct invocation is missing, though the absence of guidance on how it relates to join_forge_cohort leaves a small gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter claims are made that could conflict with the empty schema.

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

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

The description names the specific resource (Pirate Forge live sessions for the signed-in person) and scopes it to joinable sessions, distinguishing it from list_events and join_forge_cohort. It reads as a return-content noun phrase rather than a verb+resource statement, but an agent can still identify the tool's function 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?

There is no explicit when-to-use guidance and no mention of alternatives such as join_forge_cohort or my_access. The usage is only weakly implied by 'the signed-in person can still join', leaving the agent to infer when this should be called instead of the sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that it reflects identity 'as Pirate Skills knows them' and implies a signed-in/auth context, but discloses no further behavioral traits such as error behavior for unauthenticated callers.

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, tightly worded sentence with the resource and returned fields front-loaded. Every word earns its place and there is no filler.

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

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

With no output schema, the description carries the burden of describing the return value and does so by naming the two fields (name, email). It is adequate for a trivial zero-parameter identity lookup, though it could note the return shape more precisely.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter semantics for the description to clarify. Schema coverage is 100% and the empty object matches the description's implication that no input is needed.

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?

Clearly states the resource (the signed-in person's identity) and the exact fields returned (name and email), which distinguishes it from the other my_* siblings like my_access, my_bookings, and my_wallet that return different data. It doesn't explicitly name or contrast those siblings, so it falls short of a 5.

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

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

The description implies this is the tool for identifying the current user, but it gives no explicit when-to-use guidance or contrast against the many other my_* tools. An agent can infer the intent from the returned fields, but nothing is spelled out.

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

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

Annotations already declare a safe, idempotent, closed-world read, so the description is not responsible for the safety profile. It goes further by disclosing domain behavior that governs how to interpret the payload: rewards pay nothing at signup, pay on first event attendance, purchase, or Forge join, after a wait, and are voided by a refund in that window; terms.on false means rewards are paused.

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 resource and its parts, then the payout rules, then the terms caveat. It is dense with semicolons and runs long, but nearly every clause carries interpretable information about the returned fields; only the payout rule 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?

There is no output schema, so the description must carry the return shape, and it does: referral link, referees by first name and initial, gold or paid diamond, pending rewards with pay date, unpaid rewards with reason, plus the terms object and its pause flag. It stops short of stating completeness or ordering of the list, which is a minor gap for a zero-arg personal 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, which is the baseline-4 case. The description correctly adds nothing about inputs and instead spends its words on the shape of what comes back, notably the terms object read from live rules.

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

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

The description names the specific resource (the signed-in person's referral link, the referees it produced, and each reward's state) and enumerates the returned concepts, so an agent can distinguish it from my_wallet or my_access. There is no explicit verb, but 'my_referrals' plus the field list makes the retrieval 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?

Usage is only implied by the 'my_' naming convention shared with my_wallet, my_profile and my_access; the description never states when to reach for this tool versus those siblings, nor any precondition such as being signed in. It also does not say whether results cover all referrals or only a window.

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, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious semantic behavior: emerald is a textual pass string and 'never a number', earned gold expires after twelve months oldest-first, and expiresNext is a day within 60 days or null. These data-shape rules go well 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 wallet contents are front-loaded, which is good, but the run-on sentence piles parenthetical detail, a URL, and redundant emphasis ('emerald is never a number, so never give it as one') into one paragraph. It is information-dense but not tightly structured.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly, spelling out field semantics, units, and null/expiry behavior. For a single-optional-param read tool the only real gap is the unexplained limit parameter.

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

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

Schema description coverage is 0% for the single 'limit' parameter, and the description never mentions it. It refers to 'the recent history' but does not connect that phrase to the limit control, its default of 10, or its 1–50 range, leaving the parameter's effect unexplained.

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

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

The description clearly identifies the resource as 'the signed-in person's wallet' and enumerates its contents (gold.balance, diamonds, emerald pass, drip, refill date, expirations, history), which distinguishes it from siblings like my_profile, my_bookings, and my_referrals. It lacks an explicit verb ('get/retrieve'), but the resource and scope are unambiguous.

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

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

There is no statement of when to use this tool versus the many sibling my_* tools, no prerequisites, and no exclusions. The agent must infer from the name alone that wallet data belongs here rather than in my_profile or my_access.

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

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

Annotations already declare the mutation/safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the bar is lower; the description still adds that the signed-in user is the implicit subject and that non-eligible (paid) events yield an event page rather than a registration. It does not mention behavior on repeat calls (notable given idempotentHint=false) or on already-registered/full events.

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

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

Two sentences, zero filler. The action and its scope come first, with the paid-event exclusion and the id source following immediately.

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

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

For a one-parameter mutation with no output schema, the description covers who is registered, which events qualify, where the id comes from, and roughly what the response carries. The only real gaps are success semantics (immediate confirmation vs. pending) and duplicate-registration behavior.

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

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

With a single parameter at 0% schema description coverage, the description must compensate, and it does: eventId is an event id and its provenance is list_events. It adds no format or constraint guidance (length limits live only in the schema), so it is not a full 5.

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

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

States a specific verb (register), a specific actor (the signed-in person), and a scoped resource (a free upcoming event identified by id). It also draws the boundary against paid events, which is what separates it from the checkout/booking siblings.

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

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

Explicitly says when to use it (free upcoming events) and when not (paid events, where the event page is where a ticket is bought), and it points to list_events as the source of the id. It stops short of naming the sibling tool an agent should call instead for paid events (e.g. create_checkout), leaving that 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 a safe, idempotent, non-open read, so the description needn't restate safety. It adds real behavioral value: signed-in users get excerpts while anonymous callers get only codex/title/url, and it instructs citing every URL used. It stops short of pagination/ranking details, but the auth-dependent output difference is substantive.

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 corpus scope, then return shape, then the citation requirement. No filler and no repetition 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?

With no output schema, the description does the work of explaining returns (chapters, links, optional excerpts) and adds a citation obligation. It is nearly complete; the only real gap is the undocumented 'limit' parameter and query length bound.

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

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

Schema description coverage is 0% for both parameters, so the description must compensate and does not: it never mentions 'query' constraints (2-200 chars) or the 'limit' parameter that caps results at 20. Only the general notion of searching is conveyed, leaving both parameters undocumented in prose.

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 (Search) and resource (Pirate Skills knowledge) and enumerates the corpora: Growth Codex, Builder Codex, Insights. It even describes the return unit (best matching chapters with a link), so an agent knows exactly what this tool produces.

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

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

Usage is implied by the name and the search framing, and the sign-in distinction hints at context of use, but there is no explicit when-to-use/when-not guidance or named alternative. Siblings are unrelated booking tools, so routing pressure is low, keeping this at a minimum-viable 3.

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