Sonar Connections

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

The read-only annotations establish the safety profile, and the description adds substantial behavior beyond them: started slots are never returned, closed days return none with a reason, and HOURS_UNSTATED must not be described as closed. These edge-case disclosures are exactly what an agent needs to interpret results correctly.

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 definition is dense but front-loaded, starting with the core purpose before enumerating supported businesses and result caveats. Every sentence carries operational value, including the business lists and the HOURS_UNSTATED warning.

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 explains return contents and edge cases: stable slotId values, absent started slots, closed-day reasons, and the HOURS_UNSTATED distinction. Combined with full schema coverage and read-only annotations, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so the schema already documents date, business, and businessId with their defaults and refusal behavior. The description restates some of this but adds no material parameter semantics beyond the schema, making the baseline 3 appropriate.

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

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

The description gives a specific verb and resource ('Open appointment slots at a business') and clearly scopes it to one date. It distinguishes the tool from non-booking businesses and points to biz_book for the subsequent booking action, so an agent can identify it without opening the schema.

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

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

It provides clear usage context: default date, supported businesses, and that slots carry a slotId accepted by biz_book. It does not explicitly contrast with other biz_* siblings such as biz_info or biz_menu, but the operational context is strong enough to guide selection.

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

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

Goes well past the readOnlyHint annotation: it explains that `openToday` may be NULL vs false and that NULL must never be reported as closed, that `hoursNow.text` is resolved in the business's own timezone, that `schedulingSystem: Square` means bookings live elsewhere, and that `isDemo` flags demonstration data. These are exactly the semantic traps an agent would otherwise fall into.

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 return fields, then routing, which is the right ordering. However, the full enumeration of all five businesses with parenthetical descriptions duplicates the schema verbatim and bloats the description. The high-value NULL/hoursState warning is buried mid-paragraph rather than promoted.

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

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

An output schema exists, so return-value enumeration is technically redundant, but the description supplies the non-obvious interpretation rules (NULL ≠ closed, timezone resolution, schedulingSystem meaning) that a schema cannot express. For a zero-required-param read tool with full schema coverage, nothing an agent needs 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 schema already documents `business` with the same business list and the refusal behavior, so the description adds no new parameter meaning. It merely repeats the business roster. Baseline 3 is appropriate when the schema does all the work.

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

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

States a specific resource and enumerates exactly what it returns: tagline, services/menu with prices, weekly hours and today's hours. It also names concrete businesses served, so an agent knows immediately whether this tool applies. Sibling routing text ('For what a shop sells call biz_storefront') further separates it from nearby tools.

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

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

Explicit alternatives with conditions: 'For what a shop sells call biz_storefront; to book, biz_availability then biz_book.' It also gives behavioral instructions on how to speak results (never say closed when hours are unstated), which is usage guidance beyond routing. The only minor gap is that biz_menu and biz_order overlap is not addressed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description restates 'only reads', which is redundant. It adds genuine value beyond that: pickup-only, default date is today in the business timezone, and the output rule that an 'unstated' hoursByDay row must never be spoken as closed — a behavioral nuance the annotations cannot 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?

Scope and the ordering alternative are front-loaded, which is good, but the middle sags into a catalogue of four unrelated businesses with no pickup menu and a product list for the bakery. Some of that guards against wrong-business queries, yet it reads as unfiltered dump and dilutes the actionable guidance.

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

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

An output schema exists so return values needn't be explained, and the description still covers the one output pitfall agents need (the 'unstated' hoursByDay rule). Combined with the read-only annotation, it gives an agent enough 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 all three parameters are already documented, including the refusal-on-omitted-business rule and the businessId alias. The description reinforces the date default but does not add syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

Names a specific resource (the PICKUP MENU for a business) and enumerates what it returns: items, prices, allergens, notice needed, pickup windows. It explicitly separates itself from biz_order, which is the sibling an agent might otherwise confuse it with.

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?

Clearly states the complementary flow — read here, order via biz_order using item and window ids from this reply — and warns that Velvet and Clay, Brightpoint Dental, Make Collectives and Kristin Dunn Bookbinding have no pickup menu here. It never routes the agent to other read siblings such as biz_availability or biz_storefront, so the alternative coverage is partial rather than complete.

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

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

Beyond the annotations, it discloses payment behavior ('Most orders are paid at pickup; where the reply is HELD, its `payUrl` is the only payment link this connector issues: give it exactly as returned'), privacy handling ('no phone, email, surname or card is collected', note contact details removed), and the meaning of `isDemo`. This is exactly the kind of context annotations cannot carry, and it does not contradict them.

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

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

The most important constraints are front-loaded (what it does, required inputs, business scoping), and the dense business list is justified by the exclusion risk. It is a single long paragraph, so structure could be improved with sentence breaks, but there is little wasted content.

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, open-world mutation with no output schema, the description covers prerequisites, business eligibility, payment behavior, demo semantics, and privacy handling. It does not describe the full response shape beyond the HELD/payUrl and isDemo cases, but the critical invocation context is present.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real semantics: `items` and `pickupWindowId` must come from biz_menu, the business must be named because the default takes no pickup orders, and only a first name is collected. It adds cross-tool provenance rather than merely repeating field descriptions.

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

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

The description opens with a specific verb and resource: 'Places a pickup pre-order at a business served through this connector,' and immediately clarifies that it is the ordering/checkout step after biz_menu. It also scopes which businesses are served, so an agent can distinguish this tool from browsing or status-checking 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?

It gives explicit preconditions ('Needs `items` and a `pickupWindowId` from biz_menu and the collector's first name') and clear exclusions ('Velvet and Clay... Brightpoint Dental... take no pickup orders'). It does not explicitly route the agent to biz_order_status for checking an existing order, which keeps it just short of full when-to-use/when-not/alternatives coverage.

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

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

Beyond the readOnly/destructive annotations, it enumerates exactly what comes back (order state, payment state, PAID flag, pickup window, business name, total) and, critically, what does NOT (no customer name, items, payment link), plus the error path ('a code that names no order comes back not found'). With no output schema, this is the disclosure that carries the tool.

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

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

One paragraph, front-loaded with the verb and resource, then the code provenance, then the return contract, then usage, then the error case. The em-dash enumerations pack detail without padding; no sentence is filler.

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

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

No output schema exists, so the description has to describe returns — and it does, exhaustively, including the not-found case. Combined with readOnly annotations and a fully covered single parameter, 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% and the schema already documents the single parameter, so the baseline is 3. The description still adds value by identifying the code's origin (returned by biz_order) and its LBB-XXXXXX shape, which tells the agent where to source the value.

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

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

Starts with a specific verb and resource ('Read the CURRENT state of a pickup order'), scopes it to a confirmation code, and ties that code back to the sibling that produces it ('the LBB-XXXXXX style code biz_order returned'). An agent can distinguish it from biz_order and biz_storefront 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 an explicit trigger: 'Use it after a customer has been sent to a checkout page, to tell them whether the payment has landed and the order is placed.' That is clear when-to-use guidance. It stops short of naming an explicit alternative or a when-not-to-use case, which keeps it off a 5.

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

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

Beyond the annotations, it discloses the highest-risk behavior: a call without confirm changes nothing and returns a confirmToken, and only a confirm plus that token mutates state. It also adds live permission checking, ambiguous-name rejection semantics and the idempotent repeat behavior, so an agent knows exactly what each call does to the system.

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 effect and with no filler. The middle sentence packs permissions and ambiguity handling into semicolon-linked clauses, which is dense but every clause carries operational information.

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

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

For a 7-parameter mutation tool with no output schema, the description covers prerequisites, permissions, ambiguous input handling, idempotency and the two-step confirmation, and it explains what the first (preview) call returns. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds semantics the schema cannot express: itemId and itemName are alternatives (neither is required in the schema, yet one is needed), and confirm/confirmToken form a coupled pair across two calls. Only requestId's repeat behavior is not echoed in the 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?

The opening sentence gives a specific verb, resource and scope: mark one item on a business menu sold out for today, or reverse it. That single-item, today-only scope implicitly separates it from the sibling biz_availability, but no sibling is named explicitly as the alternative for store-level availability.

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

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

It states the two use cases (mark sold out, put back), the prerequisite authorization (owner or manager, checked live), and the mandatory two-step preview-then-confirm workflow, including that an ambiguous name is refused rather than guessed. It does not say when to reach for biz_availability or biz_menu instead, so routing to siblings is left to inference.

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

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

Annotations declare readOnly=false? no – readOnlyHint=true, destructiveHint=false, which covers the safety profile, and the description then adds substantive behavior the annotations cannot: 60 products per page with pageCount/total, `query` only subtracts results, one cart link per item on WooCommerce, made-to-order lead times, links must be passed through verbatim, and no payment flows through the tool. That is well beyond the annotation baseline.

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 primary trigger, which is good, but the body is a long run-on of all-caps clauses mixing platform trivia, address details, and cart mechanics. Several sentences (the Long Beach street address, the boutique description) are padding relative to the tool's job, and the shouting caps hurt legibility.

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 naming the returned fields, the pagination envelope, and the cart/shop link contract, so an agent knows what comes back. It is nearly complete; the only soft spot is not clarifying how `businessId` and `business` interact beyond the schema's own note.

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

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

Schema coverage is 100%, so `page`, `limit`, `query`, `business`, and `businessId` are already documented, and the description mostly repeats that (60 a page, query narrows). The one value-add is explaining that an omitted business defaults to a shop with no catalog and is refused, but the schema states this too. Baseline 3 is correct.

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 an explicit verb-and-resource statement ('Reads that shop's OWN published catalog: title, maker, type, price, stock and one image per product'), and the 'CALL THIS for...' clause names the user intents it serves. It never names the sibling tools (biz_menu, biz_info, biz_availability) it sits beside, so an agent separating catalog reads from menu/availability reads must infer from scope alone.

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

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

Gives explicit trigger conditions ('what a shop sells, its products, its prices, a gift idea') and explicit exclusions ('Reachable here but not through this tool: Velvet and Clay, Brightpoint Dental, Long Beach Brunch Bakehouse'). It also states the refusal behavior when `business` is omitted or ambiguous, which is exactly the routing decision an agent needs.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description is consistent with all of them (the 'not claimed twice' line matches idempotentHint). It adds useful context beyond them — the connector-token requirement, the two-step dry-run/confirm flow, and the fact that an unconfirmed call changes nothing. However, it spends several sentences restating return fields (ok, id, done) that the output schema already covers, so the incremental behavioral disclosure is good but partly pad.

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 its prerequisite, then refusal modes, then return shape, then auth, then the two-step flow — a sensible ordering. It is slightly run-on in the middle (two refusal clauses and an 'already' clause chained with semicolons), and the return-value sentence duplicates the output schema.

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, two-phase, auth-gated tool, the description covers prerequisite, auth requirement, failure codes, idempotency behavior, and the confirm handshake, while the output schema handles return values. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning by telling the agent to pass eventId and boothId exactly as booth_connect received them, and explains the confirm/confirmToken pairing as a two-phase operation rather than two independent fields. That is genuine value beyond the schema text, though it does not add format or validation detail.

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

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

States a specific verb and resource — claims a booth's swag drop into the caller's Swag Bag — and immediately ties it to the prerequisite sibling booth_connect. An agent can distinguish it from booth_connect, booth_enter_raffle, or booth_take_invite 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 the explicit precondition (a prior card swap at that booth via booth_connect) plus the exact refusal codes when the condition fails (NOT_CONNECTED, UNKNOWN_UNLOCK) and the no-op case (swag already in bag returns 'already'). It also spells out the required two-call confirm sequence, so when-to-use and how-to-sequence are both unambiguous.

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

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

Goes well beyond the annotations by disclosing the two-step confirm contract: the first call shares nothing and returns a confirmToken, and only confirm=true with that token performs the swap. It also documents the alreadyConnected case for repeat swaps and names the response fields (unlocks, cardShared), which the annotations do not cover.

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

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

Front-loaded with purpose and the app-equivalent analogy, then prerequisites, then the response contract, then routing. It is dense and clause-heavy in places (the unlock sentence is a run-on), but no sentence is filler.

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

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

Covers the full picture an agent needs for a mutating, two-phase tool: auth requirements, ID provenance, the confirm handshake, the repeat-call outcome, and where the returned unlocks are consumed. Even though an output schema exists, the named response fields help the agent branch on results.

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 ordering semantics: it explains that confirmToken is the value returned by the first call and that confirm must be paired with it. That is information not present in the field descriptions, which only restate the same relationship more loosely.

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: swaps business cards between the person and a booth at their event, and anchors it to a known user action (scanning the booth's code in the app). It is clearly distinct from the sibling booth_* tools, which it names as consumers of the resulting unlocks.

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 states prerequisites (personal connector token, a seat at the event), the source of the IDs (an events_booths row), and routes the agent onward: booth_enter_raffle, booth_claim_swag and booth_take_invite take the unlocks. It also distinguishes the two call phases, so the agent knows exactly when to make each 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?

Goes well past the annotations: it discloses the two error-refusal paths and that 'nothing changes' on refusal, the de-duplication behaviour ('already') which concretely backs idempotentHint, the auth requirement (personal connector token), and the two-step confirm/confirmToken protocol in which the first call mutates nothing. Nothing an agent could get wrong about side effects is left unstated.

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 precondition are front-loaded, and each sentence carries distinct information (precondition, errors, idempotency, return shape, auth, two-step flow). It is dense but slightly run-on, packing the two-step protocol into one trailing clause rather than breaking it out.

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, gated, two-step tool this covers everything material: prerequisite, refusal modes, idempotency, auth requirement, and the confirm handshake. An output schema exists, and the description's mention of returned fields (ok, id, done, sentence) is a bonus rather than a gap-filler.

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

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

Schema coverage is 100% and the schema descriptions already explain confirm, confirmToken and boothId in nearly the same words the description uses ('Pass eventId and boothId as booth_connect was given them' vs. 'The booth id, as booth_connect was given it'). The description adds little parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('enters them in the booth's open raffle') and pins the exact precondition that separates it from siblings ('After the person has swapped cards with this booth (booth_connect)'). An agent can distinguish it from booth_connect, booth_claim_swag and the event_* tools 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 an explicit prerequisite (a prior card swap at that booth), explicit when-not conditions with the resulting error codes (NOT_CONNECTED, UNKNOWN_UNLOCK), and names the sibling that must run first. The conditions that select or reject this tool are spelled out rather than inferred.

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

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

Well beyond the annotations, the description discloses the two-step preview/confirm protocol, that the first call 'changes nothing', the confirmToken TTL of two minutes, single-use semantics, and that the token is invalidated if 'any argument changes'. It also explains permission checks against live records. This is exactly the behavioral context annotations alone cannot 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?

It is front-loaded with purpose and effect, then requirements, then the two-step flow. The single dense paragraph packs a lot without wasteful sentences, though splitting the confirm flow into its own sentence or two would improve scannability.

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

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

For a mutation tool with no output schema, it covers everything an agent needs: auth requirements, authorization rules, the preview-then-confirm flow, what the preview returns (a description of changes plus confirmToken), token expiry, and idempotency expectations. Nothing material is missing.

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

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

Schema coverage is 100% so baseline is 3, but the description adds real semantics: confirmToken's lifecycle (returned by preview, expires in two minutes, works once, invalidated by argument changes) and the shared-token caveat. It complements rather than repeats the schema's per-parameter docs.

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

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

The description opens with a specific verb plus resource and effect: 'Marks a booth the person staffs as stepped away, or back; attendees looking at that booth see the presence change.' This distinguishes it from sibling booth tools (booth_claim_swag, booth_connect, booth_take_invite) which are about attendee actions, not staff presence on a booth.

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

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

It gives clear preconditions: a personal connector token is required because 'a shared token reads but changes nothing', and only booths the person owns, administers or staffs can be changed, 'checked against live records on every call'. It stops short of naming a sibling as an alternative for related operations, but the eligibility constraint is explicit enough to route an agent 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?

Beyond annotations that mark this as a non-destructive, idempotent mutation, the description discloses the personal connector token requirement, the card-swap precondition, specific refusal codes, duplicate-invite behavior, and the two-step no-op-then-confirm model. These details are consistent with readOnlyHint=false, idempotentHint=true, and destructiveHint=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?

The purpose and precondition are front-loaded, and the additional error, idempotency, and confirm-flow detail is justified for this two-step mutation. The sentence summarizing return values is somewhat redundant because an output schema exists, which keeps it from a top score.

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

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

Given the tool's complexity, the description covers preconditions, refusal modes, idempotency, authentication, two-step confirmation, and a brief return summary. With annotations and an output schema also present, an agent has enough information to invoke the tool correctly.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description reinforces that eventId and boothId should match booth_connect and ties confirm to confirmToken, but those relationships are also covered by the schema descriptions, so it adds workflow context rather than new parameter-level semantics.

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

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

The description states a specific verb and resource: it takes the booth's side-event invite for the person after a card swap. It also says the invite lands in the person's inbox and ties the action to booth_connect, so it is distinguishable from siblings such as booth_connect and booth_claim_swag.

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 precondition: use only after the person has swapped cards with this booth via booth_connect, and pass eventId and boothId as booth_connect was given them. It also names when the tool refuses (NOT_CONNECTED, UNKNOWN_UNLOCK), handles already-held invites, and explains the two-step confirm flow.

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: names the auth requirement, the server-side ownership check with the NOT_RECEIVER failure, the AMBIGUOUS_NAME partial-failure mode where nothing is accepted, and the ok:true success signal. The 'accepting twice changes nothing' note corroborates idempotentHint with concrete meaning rather than contradicting 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 effect, then prerequisites, then failure modes, then the return value and next steps. Five dense sentences with no filler; every clause is load-bearing.

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?

Annotations cover safety and idempotency, the schema covers parameters and there is an output schema, yet the description still supplies the missing operational context: auth token, authorization refusal, ambiguity handling, and idempotent re-acceptance. Nothing an agent needs to call it correctly is absent.

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 would be 3, but the description adds the joint semantics the per-property schema cannot: the two parameters are alternatives, both sourced from an event_requests row. It largely restates the matching scope and precedence rules already in the schema, so it is only modestly above baseline.

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

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

States a specific verb and resource ('accepts a hello the person has received') plus the effect ('opens a conversation with the person who sent it'). This clearly distinguishes it from event_say_hello, event_send_request and event_requests 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 the prerequisites (personal connector token, hello identified by firstName or requestId drawn from an event_requests row), an explicit exclusion ('only hellos addressed to the caller'), and the follow-on tools (event_inbox to read, event_reply to answer). An agent knows exactly when this tool applies and when the server will refuse.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: a hard cap of 50 rows, newest-first ordering, that email/phone values are deliberately withheld (only yes/no), the dual JSON plus numbered text-block output, and the token requirement. These are exactly the behavioral facts an agent cannot infer from structured fields.

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

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

Front-loaded with what is returned and the row shape, then constraints, then the event scoping rule. Dense and largely waste-free, though the single long paragraph mixes return shape, LinkedIn limitation, and parameter behavior in ways that would read better split, and some field detail is recoverable from the output schema.

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 read tool with full schema coverage, an output schema, and rich annotations, the description still covers the return shape, ordering, cap, privacy behavior, auth need, and sibling relationship. Nothing an agent needs in order to call it correctly is missing.

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

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

Only one optional parameter at 100% schema coverage, so the schema already documents the id/slug/name resolution and fallback order. The description restates the same fallback chain without adding syntax or format guidance beyond it; baseline 3 is appropriate.

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

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

States a specific verb (lists), specific resource (business cards received in swaps at an event), and scope ('booth scan or badge swap, in either direction'). It explicitly contrasts with the sibling event_card_save_linkedin, so an agent can separate the two without reading 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 the read-context clearly (needs a personal connector token, only reads) and names the alternative for the opposite job (event_card_save_linkedin saves the person's own link). It also explains the workflow constraint that LinkedIn invitations must be sent manually, which frames when to use this output. No explicit 'do not use when' exclusion, so not a 5.

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

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

Goes well beyond annotations: discloses the personal connector token requirement, the destructive-free but mutating nature of the write, the two-step preview/confirm protocol, and three distinct error outcomes with what happens to existing data in each case. All of this is consistent with readOnlyHint=false, idempotentHint=true, destructiveHint=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?

Front-loads purpose and the no-op conditions before the mechanics of the two-step flow, which is the right order. It is a dense single paragraph, and the parenthetical error-code insertions make it slightly harder to scan, but no sentence 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?

An output schema exists, so return-shape detail is optional, yet the description still signals ok/outcome/sentence. With annotations, full schema coverage, and a three-parameter surface, an agent has everything needed to invoke it correctly on first try.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that a call without confirm saves nothing and returns a confirmToken, and that the token must accompany confirm=true — semantics the schema states tersely. The `myLinkedin` constraint (linkedin.com/in/ URL shape) is also reinforced.

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 ('keeps the person's own LinkedIn profile link on their own ... business card') plus the gating condition ('when the card has no LinkedIn link yet'). Scope is narrowed explicitly ('It changes only the person's own card'), which distinguishes it from card-related siblings, though no sibling tool is named by name.

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

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

Gives clear conditions for action versus no-op: an existing identical link returns 'already saved', a different link yields DIFFERENT_ON_FILE, and a malformed link yields LINKEDIN_URL_INVALID. The two-step confirm flow is spelled out, but no alternative tool (e.g. event_card_links) is suggested for the cases this tool declines.

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

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

Adds far more than the annotations: it applies immediately on this call, every change is logged and reversible by the caller's own latest undo, nothing else on the event changes, no message is sent, Wallet passes update with a lock-screen notice whose count appears in `passNotice`, and host-only auth plus a personal connector token are required. It also names the exact refusal codes (NOT_A_HOST, BAD_TIME, NO_SUCH_PLACE, NO_SUCH_ENTRY, NO_CHANGE) — consistent with destructiveHint=true since guest_code invalidates the old code.

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?

Core rule and warning ('IT APPLIES THE CHANGE ON THIS CALL, one `field` per call') are front-loaded, and the ALL-CAPS section labels help navigation. But the block is a very long run-on that interleaves general rules with per-field detail, orders the labeled sections haphazardly (QUIETLY and LANGUAGE before the things they qualify), and repeats itself (quiet pass updates appear twice). Given 21 enum values some length is warranted, but tighter grouping would serve better.

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

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

For an 11-parameter tool with no output schema, the description covers what an agent needs: what the reply contains (before/after values, `passNotice`, upload link, candidate lists for ambiguous titles/places), failure modes, auth requirements, and the undo path. Nothing material is left for the agent to guess 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% so the baseline is 3; the description earns more by mapping which auxiliary parameters each `field` consumes (`venueName`, `entryTitle`, `sessionId`, `question`, `cardHost`) and by adding format rules absent from the schema: times need am/pm or unambiguous 24-hour form, guest codes 4–32 letters and digits, eyebrow 2–24 characters. The `card` sub-object is only lightly touched ('look, accent, tabs, heightCapPx, intro'), leaving the individual setting semantics 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, resource and scope: 'Change one detail of a personal event (hosts only)', one `field` per call. The enumerated field list and the explicit pointer to `event_change_undo` for reversal let an agent distinguish this from siblings such as `event_session_move` or `event_pass_reissue` without opening another schema.

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

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

Rich per-variant guidance: palette/color needs a preview then `confirm` true, cover_photo returns a one-time upload link and must be re-called, `quiet` when the host says 'quietly', refusal codes to read out verbatim. However it never routes the agent between this tool and overlapping siblings like `event_session_move`, `event_session_rename`, `event_pass_reissue` or `events_personal_card`, so the boundary is inferred rather than stated.

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

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

Goes well beyond the destructive/non-idempotent hints: it explains that the change is replayed through the same checks and into the same change log, that successive calls chain backwards, that undos are not themselves reversible, and that restoring a pass-visible detail pushes the restored line to every registered phone. That is exactly the side-effect detail an agent needs before calling a destructive tool.

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

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

Purpose is front-loaded in the first clause and nearly every sentence carries new constraints. It is dense and semicolon-chained, though, so some clauses ('restoring the value the detail had before it, through the same checks and into the same change log') read as run-on rather than crisp.

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 enumerates the return payload (the detail, before/after values, a human-readable sentence, and `passNotice` when passes are on), plus auth needs and error behavior. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and the single parameter already documents both id and name forms, so the schema carries the semantics. The description only reinforces the token requirement and names `eventIdOrName` without adding format or resolution rules, which is the baseline-3 situation.

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 scope: 'Reverses the caller's own most recent change to a wedding or other personal event they host.' This clearly separates it from the forward-mutation sibling event_change_detail and from site_undo_publish (different resource), so an agent can pick it without opening the schema.

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

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

Gives strong exclusion conditions: only hosts, only their own changes, an undo is not itself reversed, and each further call walks back the next older change. The NOTHING_TO_UNDO case is spelled out. It stops short of naming a sibling alternative (e.g. use event_change_detail to make a new change instead), so it lands just below the top.

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

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

Despite annotations already marking it read-only and non-destructive, the description adds substantial behavioral detail: only opted-in people are listed, at most 20 results, ordering by fit, the exact fit vocabulary, the meaning of why, no score/percentage/rank, privacy exclusions, and emptyReason codes.

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 is front-loaded in the first sentence, and the later sentences carry useful behavioral and privacy detail. It is dense and somewhat run-on, but most content earns its place for a tool with no output schema.

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 returned fields, privacy limits, ordering, result caps, fit semantics, why text, needsIntent behavior, and empty-reply reasons. It is complete enough for an agent to call and interpret the tool 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% for the single eventId parameter, and the schema already explains that it is optional and defaults to the current event. The description reinforces that behavior and adds the separate connector-token requirement, but does not add much parameter-level meaning 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 states a specific verb and resource: lists people at an event whose stated intent fits the caller's. It clearly distinguishes this matching/list function from neighboring tools such as event_set_intent, event_say_hello, and event_send_request.

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

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

It gives clear prerequisites: a personal connector token is required, the optional eventId selects an event the person has joined or defaults to the current event, and no intent produces needsIntent with no rows. It does not explicitly compare this tool to siblings or state when not to use it.

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

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

Goes well beyond the annotations: records who marked it and when, messages nobody, changes nothing else on the event, and repeats calls are no-ops that report `already` (consistent with idempotentHint=true and destructiveHint=false). It also discloses the auth requirement (personal connector token) and the exact refusal code, which annotations cannot 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?

Two dense, front-loaded sentences plus a short return clause; the action and its effect on the open list come first, then prerequisites, side effects, idempotency, authorization and errors. No sentence is filler.

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

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

With no output schema, the description supplies the return shape (ok, id, handled, already); with a mutation tool it supplies auth, side-effect boundaries, idempotency and the error case. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already explains both parameters, so the baseline is 3. The description adds only light scoping context — the event must be one the caller hosts and requestId must be a row id from event_guest_requests — without new syntax or format 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 — marks one guest request handled on a personal event the caller hosts — and names the sibling list tool (event_guest_requests) as the source of the id and the place the request disappears from. An agent can distinguish this from event_guest_requests, event_requests and event_reply 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?

Explicit about when to use it (marking one request handled, taking it off the hosts' open list) and where the inputs come from (a row of event_guest_requests). It also states the exclusions and failure modes: only hosts may do this, and an id that is not a request on that event is refused with NO_SUCH_REQUEST.

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 (which already declare readOnly/idempotent) by disclosing hosts-only authorization with a refusal path, an open-requests-only filter, newest-first ordering, and the exact fields returned. It also flags the PII boundary (first name or 'a guest', no phone/email/account id) and instructs verbatim handling of notes — real behavioral guidance 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?

Front-loads the resource identity and return shape before the constraints, and nearly every sentence carries operational guidance. The all-caps emphasis and the repeated verbatim-handling instruction in the last third are slightly verbose, but nothing is truly wasted.

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

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

With no output schema, the description fully specifies the return shape (category, guest note, first-name sender, timestamp, open-only, newest first), the authorization model, and how to handle refusals. Nothing an agent needs in order to call and report on this tool 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 schema already says the parameter accepts an event id or the event NAME as hosts spell it. The description adds only the framing that the event is a personal event this connector serves; no additional format or lookup semantics.

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

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

States a specific verb and resource ('the hosts' own list of what their guests have asked for') and scopes it to a personal event on this connector, which separates it from the sibling event_requests and event_inbox. An agent can identify what it retrieves without opening the schema.

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

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

Gives concrete trigger phrases ('what have our guests asked for', 'any dietary requests') and names event_guest_request_handled as the follow-up action for clearing an item. It doesn't explicitly exclude event_requests or event_inbox, so the boundary with those siblings is left to inference.

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

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

Adds substantial behavioral context beyond the annotations: it requires a personal connector token, returns no phone/email/surname/account/photo fields, and specifies NOT_PARTICIPANT and AMBIGUOUS_NAME failure cases. It also clarifies that the tool only reads and marks nothing read, reinforcing the readOnly annotation without contradicting 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?

The description is front-loaded with the core purpose and then layers invocation modes, privacy limits, and errors efficiently. It is dense and somewhat packed into one long sentence, but every clause carries useful information.

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

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

Given the read-only annotations and an existing output schema, the description is complete enough for correct invocation: it covers auth, scope, return shape at a high level, privacy limits, and error behavior. No major agent-facing gap remains.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds useful semantics for no-argument listing versus firstName/chatId lookup, including ambiguity handling, though it does not discuss the limit parameter beyond what the schema already says.

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

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

States a specific verb and resource: reads the caller's own event conversations with connected people. It also distinguishes the read-only inbox behavior from reply-style siblings by saying it only reads and marks nothing read.

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?

Explains the two main invocation modes: no arguments lists threads, while firstName or chatId returns one conversation's last lines. It adds prerequisites and participant/ambiguity errors, but does not explicitly name when to choose a sibling such as event_reply instead.

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

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

Far beyond what the annotations carry: it discloses that `text` appears on the lock screen and persists on the pass, that lat/long pairs cause the pass to resurface near a place, that the reply's `noticeId` names the meetup, that preview mode is the default and sends nothing, and the exact rate-limit ceiling with the error string returned when exceeded. Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) agree with the described dry-run/send split and the `requestId` single-send semantics.

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

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

Front-loaded with the action and audience, then requirements, then the preview/send rule, then limits — a sensible order with no filler sentences. It is tightly compressed to the point of telegraphese ('Six an hour per event, shared with event_pass_notice, then RATE_LIMITED'), which is efficient but crams auth, geofencing, and error codes into single long sentences.

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 15-parameter write tool with no output schema, the description covers the essentials an agent would otherwise get wrong: permissions, the preview-by-default trap, the geo pair constraint, persistence of the message, and the failure modes. Remaining gaps are minor — the optional `at`, `tier`, `intent`, and `serials` selectors are left entirely to the schema, and the reply's shape is only partially characterized by `noticeId` plus the preview's pass count.

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 3 is the baseline; the description adds real semantics beyond it — the lock-screen/persistence behavior of `text`, the both-or-neither coupling of `latitude`/`longitude`, the role of `noticeId` in the reply, and the preview/send meaning of `confirm`. It stops short of explaining when `audience: my_booth` or `noticeId` (the earlier-notice parameter) should be chosen, though the schema's enum listing covers the audience values.

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 first sentence names the specific action (announce a meetup), the actor (event organizer or personal event host), and the recipient set (holders of the event's Wallet pass). That is a concrete verb+resource pair an agent can match against a user request without opening the schema.

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

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

It states the decision rule for the most consequential branch: without `confirm` it returns the pass count and exact line and sends nothing, with `confirm: true` it sends. It also states preconditions (host/organizer only), rate limits, and the `my_booth` → VENDOR_OFF failure. What's missing is an explicit comparison to `event_pass_notice`, which is the nearest sibling and shares the rate-limit budget — the relationship is implied rather than routed.

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 write (readOnlyHint=false), idempotent, non-destructive. The description adds substantive context beyond them: only the answer is recorded, the organizer can then message yes-responders, and a missing pass yields NO_PASS with nothing written. It doesn't cover return shape or token acquisition details beyond naming the connector token requirement.

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 action in the first clause, followed by required inputs and then the recording semantics. It is somewhat long with a few parenthetical examples, but each sentence conveys needed information about scope or error behavior.

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

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

Given a 3-param write tool with no output schema and full schema coverage, the description covers auth (personal connector token), input provenance, persistence semantics, and the NO_PASS failure case. Only the response payload is unspecified, which is a minor gap since no output schema exists.

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

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

Schema coverage is 100% and the schema already documents all three required parameters including the yes/no enum and noticeId provenance. The description restates the same provenance (the pass carries noticeId, the organizer's reply did) rather than adding syntax or format detail, 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 specific verb and resource: it records a pass holder's own yes/no answer to a meetup notice, and explicitly scopes it to the person's own pass record. This cleanly separates it from siblings like event_meetup_announce (organizer side), event_pass_notice, and event_reply.

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 establishes clear context: this is the attendee answering an organizer's notice, and the organizer can later notify everyone who said yes. It clarifies what is out of scope (no note, time, or name), but does not name a specific alternative sibling tool or state when NOT to use this one.

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 readOnly/idempotent/destructive, but the description adds substantial non-obvious behavior: the organizer-only permission model, a refusal that 'says nothing about the event', the requirement for a personal connector token, and that aggregates exclude person names/ids. It also discloses read-after-write consistency with the session-mutation tools.

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 content is dense and front-loaded with the core purpose, but much of it is a single sprawling sentence that enumerates every returned field. Since an output schema already exists, that long enumeration is redundant and hurts scannability rather than adding value.

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

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

Permission boundaries, auth requirement, side-effect profile, and data-privacy behavior are all covered, which is what an agent needs to call this safely. Return values are partly duplicated from the existing output schema, so the description is more than complete rather than under-specified.

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

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

Schema coverage is 100% and there is a single parameter, so the schema fully documents eventIdOrName. The description adds no format or syntax detail beyond the schema's own description of 'event id or the event name as the organizer spells it,' 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 specific verb and resource with scope: 'The organizer's own overview of their event, read only,' then enumerates what it contains (name, visibility, dates, agenda, booths, doors, visit counts, links). This clearly separates it from guest-facing siblings like events_overview or events_get, though it never names those alternatives explicitly.

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

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

Usage is implied: it's for organizers, and 'After an agenda change through event_session_move... it shows the change' hints at a refresh-after-mutation context. However, there's no explicit statement of when to use this versus events_overview or events_get, so routing to the right sibling still requires 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses distinctive behavior: the preview-then-send flow, that the notice persists on the lock screen, a specific rate limit (six an hour per event, then RATE_LIMITED), the VENDOR_OFF outcome for 'my_booth', and the permission refusal path. That is exactly the operational context annotations cannot express.

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

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

It is front-loaded with the core action and the two-step mechanics, and nearly every clause carries information (error codes, rate limit, authorization). The dense telegraphic phrasing ('my_booth' returns VENDOR_OFF) is efficient but slightly compressed, keeping it just below a top score.

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

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

For a 10-parameter mutation tool with no output schema, the description covers what an agent needs: required inputs, the preview return value ('the number of passes and the exact line'), the send semantics, and the failure modes. Nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns above baseline by explaining what the audience enum members actually mean ('everyone, one ticket tier, one badge intent, listed pass serials, the people who scanned at a booth, or the people who answered an earlier meetup yes or no') and by clarifying that confirm drives preview vs send. It does not explain noticeId, requestId, tier, intent, or boothId relationships, so it stops short of a 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?

The description states a specific verb and resource ('Sends a notice from the organizer...to the people who added the event pass to their Wallet') and explicitly carves out the scope it does not cover ('It reaches pass holders only; it does not say who else is there or report that a person arrived'). It also names the sibling tool that handles the adjacent case, event_meetup_announce, so an agent can distinguish the two 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 explicit when-to-use guidance and a required two-step pattern: 'without `confirm` it returns the number of passes and the exact line and sends nothing; with confirm true it sends.' It names the redirect case ('A meetup with a place is event_meetup_announce') and the authorization condition ('Only the hosts or the organizer can send; anybody else is refused'), leaving little to inference.

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

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

Goes well beyond the annotations: the old code stops working immediately, the exact on-device message shown, and that the pass updates in place rather than being re-added. It also discloses the authorization model (self, or host/organizer when serialNumber is supplied), which the annotations do not carry.

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

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

Front-loaded with the action and the reason for it, and most sentences carry distinct information: scope, side effect, in-place behavior, permissions. The closing note that it returns the outcome in one sentence is largely redundant given the tool has an output schema.

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

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

For a destructive, non-idempotent mutation with an output schema, the description covers everything an agent needs: what changes, what stops working, that the pass is not re-added, who may act on whose pass, and which parameter selects the scope. Return values are handled by the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real value beyond it: serialNumber's presence changes both the target and the required caller role, and eventIdOrName accepts an id or the name as organizers/hosts spell it. The serial format detail (ps_ + 24 chars) is left 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: gives a Wallet pass a new QR code, and additionally un-revokes a revoked pass. This clearly separates it from siblings like event_pass_revoke and event_wallet_pass without requiring the reader to open either schema.

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

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

Gives concrete triggering situations (pass was photographed or shared, a guest's pass a host wants refreshed) and states the role conditions for acting on someone else's pass. It does not explicitly name alternatives such as event_pass_revoke for revoking or event_wallet_pass for obtaining a pass, so routing is implied rather than spelled out.

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

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

Goes well beyond the annotations: it discloses the immediate effect ('code stops working at once'), that the pass is updated in place rather than re-issued ('Nothing is re-added'), platform scope (iPhone and Android), and a caller-role restriction. These are exactly the operational facts an agent needs before invoking a destructive, idempotent write, which annotations alone only flag but do not explain.

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 effect on the pass and packed with useful detail in five sentences. Slightly overwrought at the tail ('Returns the outcome in one sentence'), which is redundant given the output schema, but nothing else is filler.

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

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

For a destructive, role-gated mutation with two params, the description covers effect, reversibility, target selection, authorization, and platform behavior; the output schema carries the return shape, so the brief mention of a one-sentence outcome is sufficient. No material gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine conditional semantics: omitting serialNumber targets the caller's own pass, while supplying it targets a specific pass and requires host or organizer rights. That mapping from parameter presence to authorization scope is not in the schema.

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

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

States a specific verb and resource ('Voids a Wallet pass on the phone') and immediately names the sibling that reverses it (event_pass_reissue). An agent can distinguish this from event_pass_notice, event_wallet_pass, and event_pass_reissue 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 describes the use case ('For a pass that was photographed or shared, or a guest's pass that a host ... wants voided') and names the inverse tool for undoing it. It also states the permission model that gates the action, so the agent knows when it can and cannot call it.

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

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

Beyond the annotations it discloses the things an agent could get wrong: the two-step preview/commit protocol, that the preview changes nothing, and that the confirmToken expires in two minutes, works once, and is invalidated if the code changes. Those details (token lifetime, single use, invalidation on code change) are not derivable from idempotentHint/destructiveHint and materially affect retry behaviour.

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 preconditions are front-loaded and almost every sentence carries information. There is minor redundancy — 'changes nothing' appears twice (once for the shared token, once for the first call) — which could be tightened, but nothing is padded.

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

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

For a two-phase mutation tool the description covers auth, sequencing, token lifetime, retry/idempotency implications and scope of use, and an output schema exists so return shape needn't be spelled out. An agent has everything needed to invoke it correctly on the first attempt.

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%, yet the description still adds meaning: it establishes that no event id parameter exists because the code resolves the event, and it explains the runtime relationship between confirm and confirmToken (the token is the one returned by the first call). That is genuine protocol semantics, not a restatement of field docs.

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 sentence gives a specific verb and outcome ('Seats the person at an event with an event code') and immediately scopes the input ('the code names its own event, so no event id is taken'). This clearly separates it from siblings like event_pass_reissue or event_pass_revoke, which act on passes rather than seating via a code.

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 explains the exact call sequence (first call without confirm, second with confirm true and the confirmToken) and the auth precondition (personal connector token; a shared token reads but changes nothing), plus the clarification that redeeming works remotely. What it lacks is an explicit 'use this instead of X' comparison against neighbouring tools, so it stops 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?

The description adds substantial behavior beyond annotations: delivery is synchronous and cannot be unsent, only the caller's own conversation is allowed, and specific error codes such as NOT_PARTICIPANT, AMBIGUOUS_NAME, and RATE_LIMITED explain failure modes. It also notes that `ok:true` does not imply a reply, which is valuable operational context.

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

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

The description is compact and front-loaded: it states the action, required inputs, irreversibility, scope restriction, and error semantics without unnecessary filler.

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

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

For a non-idempotent send operation with no output schema, it covers the essential context an agent needs: input source, immediate delivery, irreversibility, participant restriction, ambiguity handling, and rate limiting.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still adds meaningful semantics by saying `firstName` or `chatId` should come from event_inbox and that `text` must be the person's own words, though the connector token is not present in the schema.

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

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

The description uses a specific verb and resource: it sends one message into an existing event conversation. It also distinguishes the action from starting a new conversation by requiring a conversation the caller already has and referencing event_inbox-provided identifiers.

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

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

It gives clear usage context: call this to reply into an existing conversation, using `firstName` or `chatId` from event_inbox. It also states the caller's own conversation restriction and maps failures to specific conditions, though it does not explicitly compare against the sibling event_say_hello.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds value beyond them: the auth prerequisite (personal connector token) and an explicit privacy boundary (no phone, email, surname, account id or photo). That privacy disclosure is exactly the kind of behavioral context annotations cannot 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?

Three tight sentences: purpose and ordering first, then auth/scope, then return shape and privacy limits. No filler or repetition.

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

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

For a zero-parameter read tool with annotations and an output schema, the description covers everything an agent needs: what it returns, the auth requirement, the scope restriction, and the downstream handoff to event_accept.

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

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

Zero parameters, so no parameter semantics are needed; baseline applies. The description instead characterizes the returned rows (first name, here-for line, timestamp, requestId), which is useful but belongs to output rather than input semantics.

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

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

States a specific verb and resource ('Lists the hellos waiting on the person at an event') plus ordering ('newest first'), and scopes it to the caller's own pending hellos. The mention of requestId that 'event_accept takes' also positions it relative to that sibling.

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

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

Gives clear context for use: requires a personal connector token and returns only the caller's own pending hellos, which is a real selection constraint. It stops short of explicitly contrasting with siblings like event_guest_requests or event_inbox, so it is a 4 rather than a 5.

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

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

Goes well beyond the annotations: it discloses the auth requirement (personal connector token), that the send is atomic ('single call: the hello is sent when the call succeeds'), the full set of failure reasons (not_in_pool, ambiguous, already_sent, no_seat, rate_limited) with their meanings, and the important caveat that success says nothing about acceptance. This is consistent with idempotentHint=true, since a repeat call yields already_sent rather than a duplicate send.

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 effect, then constraints, then failure modes — a logical order. It is dense and longer than typical, but nearly every sentence (auth requirement, pool check, error semantics, acceptance caveat) carries operational weight rather than filler.

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

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

For a single-parameter mutation with an output schema present, the description covers everything an agent needs: prerequisites, input spelling rules, server-side validation, all documented failure reasons, and what success does and does not imply. Nothing material is left to inference.

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

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

Schema coverage is already 100%, so the baseline is 3; the description nonetheless adds real meaning by explaining the firstName must match the event_find_matches spelling exactly, excludes surname and account id, and ties the ambiguous case to duplicate first names.

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

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

The description states a specific verb and resource — sending a hello (connection request) to a person in the caller's event matches — and explains the downstream effect (a conversation opens). It clearly ties the name to an event_find_matches row, but it never contrasts itself with close siblings like event_send_request or event_accept, so an agent must infer the boundary.

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

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

Implicit but strong: it says the name must be spelled as an event_find_matches row spelled it and that the server verifies the person is in the current match pool, which tells an agent to run a match lookup first. It also states a prerequisite personal connector token. It stops short of naming alternatives or stating when not to use it.

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

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

Annotations already cover the read-only, closed-world safety profile, so the description clears the lower bar and adds genuinely behavioral detail: the meaning of `mapless: true` (in catalog but no floor position) and how to handle it in conversation versus a placed row. It also discloses the filter's matching rule (case-insensitive substring across category, name and description). It does not say whether `category` filtering also applies in single-booth mode, which is a minor residual gap.

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

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

Three sentences, front-loaded with the resource and its fields, then the mapless caveat, then the filter rule. Every sentence carries information, though the entrance-handling clause is slightly verbose for what is a presentation instruction.

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

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

With an output schema present, the description need not explain return values, yet it helpfully names the key fields and their semantics (printed aisle label, blurb, mapless flag). The one omission that matters is the single-booth mode triggered by `boothNameOrId`, which changes the result from a list to one full card and is only documented in the schema.

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

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

Schema coverage is 100%, giving a baseline of 3, but the description earns an increment by specifying that the category filter is a case-insensitive substring matched against category, name and description — a materially broader matching rule than the schema's 'Optional category filter, e.g. "dessert"' suggests. It says nothing about `boothNameOrId`, which switches the response shape to a single full card; that behavior rests entirely on 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 opens with a specific verb+resource ('Booths and vendors at an event') and enumerates the returned fields, so an agent knows exactly what it gets. It does not name a sibling it is not (e.g. events_floor_card for a spatial rendering, events_speakers for the speaker list), so differentiation is left implicit rather than stated.

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

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

Usage is implied by the field list and by the instruction to 'tell the person to ask at the entrance' for mapless rows, which gives real presentation guidance. But there is no explicit when-to-use or when-not-to-use versus events_floor_card or events_speakers, and the description never mentions the single-booth lookup mode, so the agent has to infer the selection condition from the schema.

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

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

Beyond the annotations it discloses the crucial side-effect boundary (nothing on the event is changed, nothing is arranged or approved), two named error semantics (RATE_LIMITED, BAD_NOTE), and the auth requirement of a personal connector token. This is exactly the context the destructiveHint=false / readOnlyHint=false combination cannot 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?

Caps-led sentences front-load the purpose, then the when-to-use, then the no-side-effect warning and error codes, which is a sensible priority order. Nothing is redundant, though the all-caps emphasis across nearly every sentence is slightly heavier than 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 three-required-parameter write tool with no output schema, the definition covers purpose, trigger, side effects, auth, and failure modes. The only minor gap is whether repeated identical calls create duplicate requests for the hosts, which is implied by RATE_LIMITED but never stated.

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 note length limits, the category enum, and eventIdOrName are already documented; baseline is 3. The description's example phrases clarify what a note should contain, but it adds no syntax or lookup guidance for eventIdOrName beyond what the schema states.

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

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

"A GUEST ASKS THE HOSTS FOR SOMETHING" plus the specification that it files a need or question for the hosts of a wedding or personal event is a precise verb+resource+actor. It is clearly distinguishable from sibling tools like event_requests or event_guest_requests, which read the host-side list rather than file a new ask.

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

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

It states the triggering condition concretely ("when somebody wants to tell the hosts ... about a need or a question") and gives two example utterances that map directly to call situations. It also draws a boundary on what to say afterwards, though it does not name a specific sibling alternative for viewing or answering requests.

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

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

Annotations only say this is a non-read-only, non-destructive, non-idempotent write; the description goes well beyond them by disclosing the dry-run preview contract, that the first call changes nothing, the quiet-by-default notification behavior, and the authorization failure mode. That is exactly the extra context the annotations cannot carry.

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

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

Front-loads the action and scope, then the confirmation protocol, then the authorization constraint. Dense but every sentence carries distinct information; some clauses are compressed to the point of terseness ('read out as given').

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

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

For a 10-parameter mutation tool with an output schema, the description covers the workflow, the required permissions, the side-effect profile and the optional notification path. Return-value detail is correctly delegated to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by naming the core fields (title, start, end, room) versus the optional ones (date, speakers, notify) and by explaining the confirm/changeId pairing semantically rather than syntactically. It stops short of describing accepted time formats, which the schema already handles.

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 plus a scope qualifier ('Adds a new session to the agenda of an event the person organizes'), which cleanly separates it from event_session_move, event_session_rename and event_session_cancel.

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?

Prescribes the exact two-step workflow: first call without `confirm` returns a preview, and the second call requires `confirm: true` plus the returned `changeId` after the user agrees. It also states the preconditions (organizer-only, personal connector token), leaving nothing to inference.

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

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

Annotations declare destructive/non-readonly/idempotent, but the description adds what those hints cannot: the cancellation is soft ("kept on record"), side effects are suppressed unless `notify` is true, the preview enumerates pass holders who would be notified, non-organizers are refused, and a personal connector token is required.

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

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

Front-loaded with the purpose, then ordered by decision sequence (preview → confirm → identify session → permission → auth). It is dense to the point of being a run-on sentence chain, but each clause carries operational information rather than filler.

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

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

For a destructive, confirmation-gated mutation this covers everything an agent needs: the confirmation workflow, session identification, permission model, notification behavior, and credential requirement. Return values are partly described even though an output schema already exists, so nothing material is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter and sets a baseline of 3. The description goes further by explaining the cross-parameter contract — that `changeId` is produced by the preview and must be echoed with `confirm` — and by stating that `sessionId` and title are alternatives that can be disambiguated with time.

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 ("Cancels one session on the agenda of an event") plus the ownership scope ("the person organizes") and the resulting state ("marked cancelled and kept on record"). That last clause cleanly separates it from event_session_move and event_session_rename, which also act on session records.

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 two-step protocol: first call without `confirm` to get a preview, read it back to the organizer, then re-call with `confirm: true` and the returned `changeId`. It also covers the ambiguity path ("on AMBIGUOUS or NO_SUCH_SESSION read the candidates back and ask") and the authorization failure path, leaving nothing to inference.

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

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

Goes well past the annotations: it discloses that the preview changes nothing and returns a changeId, before/after, notification count and notice text; that pass holders are notified unless `notify` is false; that non-organizers are refused with the reason surfaced verbatim; and that a personal connector token is required. This is consistent with destructiveHint=true and idempotentHint=true rather than contradicting them.

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

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

Front-loads the core action, then the preview protocol, then identity resolution, then permission and auth — a sensible order for an agent to consume. It is dense with semicolon-chained clauses, so each line does earn its place, but the run-on final sentences cost some readability.

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

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

For an 11-parameter, destructive, token-gated mutation with a required confirmation handshake, the description covers workflow, safety, error handling and identity resolution. Return values are covered by the existing output schema, so nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real semantics the schema cannot express: the `confirm`/`changeId` pairing, the effect of `notify` (quiet vs. pass-holder notification), and the interplay between `sessionId` and `sessionTitle` when disambiguation fails. It does not explain how `at`, `date`, `start` and `end` combine, which is where the remaining ambiguity sits.

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 ('Moves one session on the agenda of an event') along with the exact mutation surface (start time or room) and the authorization boundary ('an event the person organizes'). The concrete example ('push the keynote to 4:30 PM') removes any doubt about intent, and it is clearly distinguishable from siblings like event_session_add, event_session_cancel and event_session_rename.

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 two-step protocol: first call without `confirm` for a preview, then re-call with `confirm: true` plus the returned `changeId` only after the organizer agrees. It also names the required alternative when the session reference is ambiguous ('on AMBIGUOUS or NO_SUCH_SESSION read the candidates back and ask') and the fallback naming path (sessionId or title).

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: discloses the preview/confirm two-phase protocol, that the preview is non-mutating and reports who would be notified, that `notify` is quiet-by-default, and that only the event organizer may act and others are refused. Annotations (destructive, idempotent) are consistent with, not contradicted by, this text.

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 action and the preview requirement, and no sentence is filler. The semicolon-chained clauses make it dense and slightly run-on, but every clause carries operational information.

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

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

For an 8-parameter mutation with auth constraints and a two-step protocol, this covers everything an agent needs: sequencing, authorization, ambiguity handling, and what the preview returns. An output schema exists and the description still summarizes the preview payload appropriately.

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; the description earns extra by explaining relationships the schema cannot express — `confirm`/`changeId` must come from a prior preview, `notify` controls pass-holder notifications, and `sessionId`/title are alternatives for the same identification job. It stops short of explaining `at`'s disambiguation role, which stays in the schema.

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

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

States a specific verb and resource ('Renames one session on the agenda of an event') plus the scope constraint that the caller must be the organizer. Siblings like event_session_move, event_session_cancel and event_session_add are clearly different operations, so an agent can route without opening a schema.

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

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

Gives an explicit procedure: first call without `confirm` to get a preview, read it back, and only re-call with `confirm: true` plus that `changeId` once the user agrees. It also names the ambiguity/not-found paths ('on AMBIGUOUS or NO_SUCH_SESSION read the candidates back and ask') rather than leaving error handling 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?

Adds behavior well beyond the annotations: it discloses the auth prerequisite (personal connector token), the validation rule that a badge missing a first name or either sentence is refused with a `needs` explanation, the preview/confirmToken write protocol, and that the write replaces prior text. This contextualizes destructiveHint=true and idempotentHint=true rather than contradicting them.

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

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

Effectively front-loaded — the purpose lands in the first clause, with prerequisites, validation, event resolution, and the two-step flow following in descending order of importance. Sentences are dense but each carries a distinct fact; only the confirm-token sentence is slightly awkward to parse.

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

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

For a 13-parameter, nested-schema mutation tool with an output schema, the description covers the things an agent must know to call it correctly: auth, event defaulting, validation failure signaling via `needs`, and the preview/commit contract. Return values are left to the output schema as intended.

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

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

With 100% schema coverage the baseline is 3, but the description adds real semantics: it maps the badge concept onto headline/lookingFor/discoverable, explains the confirm/confirmToken pairing, and states the default event resolution when no event id is supplied. It leaves the nested `facets` object (which carries its own `confirm`) and `label`/`intent` unexplained.

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

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

States a specific verb and resource ('Sets the person's event badge') and names the three fields it governs (headline, lookingFor, discoverable), plus the resolution rule for which event applies. It scopes itself ('changes only that person's badge'), though it never explicitly contrasts with adjacent siblings like event_change_detail or events_personal_card.

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

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

Gives clear operational context: requires a personal connector token, defaults to the person's current event when no event is given, and spells out the two-step preview-then-commit flow. It does not name an alternative tool or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: it explains the inline card rendering, the fallback of returning event summary and booth directory, the hasFloorplan false case, and an operational instruction not to offer to fetch the plan. It stops short of describing authentication or rate limits, but those are not essential here.

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

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

The description is front-loaded with the purpose and packs usage, behavior, and fallback guidance into four efficient sentences. The all-caps emphasis ('THE FLOOR PLAN TOOL') is mildly redundant with the title, but the text remains tight and every sentence carries information.

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

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

Given that an output schema exists, the description need not explain return values in full. It nonetheless covers the main behavioral variations (inline card vs. summary and directory), the no-floorplan case, and the directive not to promise a picture, making it sufficiently complete for an agent to call the tool correctly.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema, including short-form examples. The description adds no further meaning about the eventIdOrSlug parameter, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource ('DRAWS THE FLOOR INLINE') and immediately enumerates the kinds of requests it handles ('floor plan, a map, a layout, a booth location'). It distinguishes itself from web knowledge and makes clear that it is the floor-plan tool, so an agent can identify it without opening the schema.

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

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

It gives clear when-to-use conditions ('for any ask about a floor plan...') and says to prefer it over web knowledge. However, it does not explicitly name sibling tools like events_booths or events_overview as alternatives, leaving the routing boundary between booth-directory calls and this tool ambiguous.

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 readOnly/non-destructive annotations: discloses the auth requirement (person must be signed in), the Connect-prompt/mobile-number sign-in flow, that the call is retried afterward, and an alternate matchDoor door for people who don't want to sign in. Minor deduction because it doesn't say what happens if the event id/slug is not found.

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

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

Front-loaded with purpose and return contents, then prerequisites and alternatives. It is a dense single paragraph with long compound sentences, and the trailing matchDoor sentence sits somewhat apart from the main call decision, but no sentence is disposable.

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

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

Output schema exists so return shape needn't be described, yet the description still previews the payload fields. For a single-parameter read tool it covers purpose, prerequisites, auth flow, alternatives, and the no-sign-in fallback — everything needed to invoke correctly.

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

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

Schema description coverage is 100% and the schema itself already documents eventIdOrSlug including the relaxed 'short forms such as "the stroll"' behavior, so the description's 'Accepts the event id or its public slug' adds nothing new. Baseline 3 applies; the schema carries the parameter burden.

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

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

States a specific verb and resource: 'Full detail for one event', and enumerates what that detail contains (kind, booth count, live offer count, agenda items today). It implicitly separates itself from list/overview siblings by emphasizing single-event depth, though it never names events_list or events_overview as the alternatives it replaces.

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 away to `event_find_matches` for matching/introductions, and gives a prerequisite ordering rule: 'If they have not said what they are here for yet, call event_set_intent first'. It also states the fallback condition (matchDoor link) and that it must be offered, never required — clear when/when-not guidance.

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

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

Annotations already declare readOnly/openWorld=false/destructive=false, so the safety profile is covered. The description adds real behavioral guidance beyond that: `kind` is the organizer's own wording, may be absent, and must never be guessed — a genuine data-quality warning. The rest of the field enumeration partially duplicates the output schema, keeping it below a 5.

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

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

Two sentences, zero filler. The field inventory comes first and the actionable "call this first" directive is placed at the end where it is most likely to be read as the final instruction.

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?

A parameterless list tool with full annotations and an output schema needs exactly this much: what comes back, the one ambiguous field explained, and how it relates to downstream tools. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and no schema gap to compensate for. Baseline 4 applies; there is no parameter text that could improve or harm this.

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

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

Specific verb + resource ("List the Sonar Connections events") with an explicit scope qualifier ("available through this connector") and an enumeration of the fields returned. An agent can distinguish it from events_get/events_overview/events_booths 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?

"Call this first to discover which event ids the other events_ tools accept" gives a clear entry-point condition and ties it to the sibling family. It stops short of contrasting with look-alikes such as events_overview or events_whats_on, so the routing is strong but not exhaustive.

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