Pirate Skills

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

Goes well beyond the annotations by disclosing the diamond hold-then-spend lifecycle, the typical confirmation latency ('usually within a minute'), the refund on failure, and the reversibility path via move_booking/cancel_booking. Annotations only say it is a non-idempotent write with no destruction; the description supplies the actual economic and timing consequences.

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 cost, and every sentence carries information about cost, timing, or follow-up. Phrasing is occasionally awkward ('The answer's booking has its own label'), which costs a point but does not obscure the meaning.

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

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

For a 3-parameter mutation with no output schema, the description covers cost, timing, failure refund, and follow-up tools adequately. It omits what happens when the person lacks diamonds or the hour is already taken by someone else, which an agent would benefit from knowing before calling.

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 parameter's own description already states it must be passed exactly as my_bookings lists it, so the description's 'pass its start exactly as listed' largely repeats structured data. The instruction to name the hour by its label rather than a computed weekday adds intent but refers to a label that is not a parameter, so it is more confusing than clarifying.

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 ('spend ... diamonds on a one-to-one hour with Ben') with an explicit precondition tying it to my_bookings. An agent can distinguish it from book_intro_call, register_for_event, and the other booking siblings without opening any schema.

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

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

Gives a clear precondition (the hour must come from my_bookings) and explicitly routes post-booking actions to move_booking and cancel_booking. It does not, however, state when this tool should not be used versus other booking siblings such as book_intro_call.

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 carry the generic hint set, so the description carries real weight and delivers: the one-upcoming-free-call-per-person refusal condition, that the refusal names the existing booking, that nothing is charged, and that the invite originates from cal.com. It even explains the returned booking's label and join link and how to move or cancel it.

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 constraint, and every sentence carries operational information. It is dense and repeats 'free 30-minute intro call with Ben' several times, which costs a point on tightness but not on clarity.

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 describing the resulting booking object (own label and join link) and the tools that operate on it. Combined with the eligibility rules and refusal behavior, 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 100%, so baseline is 3; the description goes beyond it by constraining 'start' to be passed exactly as my_bookings lists it and to be named by its label rather than a computed weekday. Topic and timeZone semantics are left entirely to 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 ('Book the signed-in person a free 30-minute intro call with Ben') and implicitly separates itself from the sibling book_hour_with_ben by naming the 30-minute intro call. An agent can tell exactly what this does without opening the schema.

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

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

Explicit when-to-offer (Forge Pass / working with Ben one-to-one, incl. Captain on Deck), explicit when-not (never for Pirate Pass or event tickets), and explicit routing ('Book it here: do not send the person to a booking page unless this refuses or fails'). It also names the follow-up alternatives move_booking and cancel_booking.

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?

Goes well beyond the annotations: no charge, the diamond is retained for an hour, the intro call stays free, the calendar invite is re-sent, and the response carries the new label. It also enumerates the exact refusal reasons, which nothing in the structured fields conveys. Annotations (non-read-only, non-destructive, non-idempotent, closed-world) are consistent and supplemented rather than repeated.

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 scope, and every sentence carries information (sources, charge behavior, refusal cases). It is a single dense paragraph with stacked parentheticals, so it is readable but heavier 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?

No output schema exists, yet the description states what the answer contains (the booking with its new label) and what failure looks like (a refusal with a reason). Combined with prerequisites, charging behavior, and per-kind start sources, 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 100%, so the baseline is 3, but the description adds real operational meaning: 'start' must be copied exactly as listed and named by its label rather than a weekday the agent computes, which guards against a common failure mode. It is silent on the timeZone parameter, which is covered only by 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 ('Move one of the signed-in person's own upcoming bookings') and immediately narrows scope to exactly two bookable kinds (the free intro call, an hour with Ben). It is clearly distinguishable from book_hour_with_ben, book_intro_call, and cancel_booking 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?

Explicitly routes the agent to my_bookings and the canMove flag for eligible bookings, then tells it where each kind's target start must come from (openHours vs introCall.moveTimes). It also lists the refusal conditions (not theirs, cancelled, begun, awaiting calendar, time not open), which is effectively a when-not-to-expect-success guide.

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.