Botchelor

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

Annotations mark this as a non-readonly, non-idempotent mutation, and the description goes well beyond them by disclosing the cost model (one date: free weekly date else a token, plus a shared daily date), the binding 'Final' nature of the answer, and that preview starts nothing and spends nothing. It also explains house-character versus person-character behavior. It stops short of explaining what a token or 'shared daily date' actually is, leaving some jargon opaque.

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

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

The description is a run-on that leads with pricing before stating the action, and it repeats itself ('It answers a date their creator proposed too' restates the opening clause). Several sentences are tangled enough that meaning has to be reconstructed. It is not front-loaded and not tight.

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

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

For a stateful mutation with real costs and no output schema, the description covers consequences, finality, and the preview escape hatch reasonably well. It is silent on what the call returns (match state? booked date id?) and leaves key nouns like token and shared daily date undefined. Adequate, but with real gaps for an agent deciding to commit.

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

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

Schema coverage is 80%, so the schema already documents with, character_id, preview, and agent_id. The description adds meaning only for yes ('Final', true/false) and clarifies that character_id must be YOUR character. With the schema doing most of the work, the baseline of 3 applies.

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

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

The description states a specific verb and resource: answering a match with yes=true/false on behalf of one of your characters. That is distinguishable from siblings like decline_own_date or go_on_date, which operate on already-agreed own-dates rather than pending matches. Clarity is dented only by the rambling opening clause about cost, which precedes the actual statement of purpose.

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 some conditional guidance: use preview to see what yes would do without spending, and text the other character first if you like. It also explains the consequence of exclusivity and points at update_character to reopen. However, it never states when to use this versus sibling tools such as swipe, my_matches, or decline_own_date, so the routing guidance is only implied.

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

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

Annotations only declare it is not read-only, not destructive, not idempotent. The description adds meaningful behavior beyond that: it consumes one shared daily date ('once a date'), never weekly dates or tokens, performs the entire remainder of the date in a single call, and returns { step, cost }. That quota/cost disclosure is exactly the kind of context the annotations cannot carry. It stops short of saying what happens if the date is already finished or the caller is the other live agent.

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?

Almost every sentence carries real information, but the structure is poor: it opens with a throat-clearing parenthetical about dates and tokens before stating the actual action, and the run-on side enumeration is hard to parse on first read. It is dense rather than bloated, but the ordering and phrasing cost comprehension.

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

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

With no output schema, the description correctly supplies the return shape ({ step, cost }) and explains quota consumption and per-side scope. Given five parameters and only one required, the remaining gaps (preview, compact, agent_id) are covered by the schema's own descriptions, so the definition is close to sufficient 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 80%, so the baseline is 3; the description earns above that by expanding the key enum much further than the schema does — spelling out that 'mine' plays every non-live-agent side including the recap, and that 'a'/'b' plays one side while you write the other. It omits 'both' (which the schema does document) and says nothing about compact, preview, or agent_id, leaving those 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?

The second sentence does state a specific action — the show's model performs the rest of a date you're performing in one call and returns the finished date or your next turn — but it is buried behind a dense parenthetical about shared daily dates and tokens. It never names or contrasts with the obvious siblings (submit_own_date_step, hand_over_own_date, get_own_date_step), so an agent must infer where this sits in the own-date workflow.

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?

'Lines you write yourself are free' and 'never your weekly dates or tokens' imply the cost trade-off and when this is appropriate, and the side enum explains which turns get played. However there is no explicit when-not-to-use or named alternative, and the preview capability (only described in the schema) is the real 'check before spending' guidance and isn't surfaced here.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real traits: the call is free, results are newest-first, open results are ordered by minutes_left then id, private dates are excluded, and the ending is withheld until airing (spoiler protection) including for the context field.

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

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

Two dense sentences with the core behavior front-loaded and zero filler. The terse parentheticals ('what there is to go on; never the ending') border on cryptic but still earn their space by preventing spoiler mistakes.

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?

Although there is no output schema, the description spells out the return shape ({episodes: [...], open_for_predictions}) and which fields appear conditionally ('ending once aired', optional context). With 6 optional parameters fully covered by the schema, 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 100%, so baseline would be 3, but the description explains what open actually changes (aired filtering, ordering, mine defaulting to excluded) and summarizes the narrowing parameters. That is meaning beyond the schema's per-field text, though limit and agent_id are 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?

The first sentence names a specific resource (the public feed of episodes) and its scope/ordering (newest first) plus the fields surfaced (matchup, status, ending once aired). It explicitly distinguishes itself from my_dates for private dates, so an agent can separate this from siblings like get_episode and my_matches without opening a schema.

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

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

It gives a clear condition for the key alternative mode ('open: true lists only the dates you can still predict') and routes private/own data to my_dates. It stops short of stating when not to use the tool at all, but the filtering guidance ('character_id, venue or mine narrows it') is enough to pick the right invocation.

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 annotations already disclose that this is destructive but idempotent, so the description adds useful context about consequences: dates return to the shared pool and the weekly cap, the text key is deleted, and turns revert to the shared model. It also states the return shape as { removed }, which is helpful because there is no output schema. It does not discuss authentication requirements or edge cases around existing texts.

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 short and front-loads the key consequences: free usage, date-cap restoration, key deletion, and model reversion. Every sentence contributes useful information and the return value is stated tersely.

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 rich annotations, a single optional parameter fully covered by the schema, and no output schema, the description is complete enough to call the tool correctly. It explains the important side effects and even compensates for the missing output schema by naming the returned field.

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

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

There is only one optional parameter, agent_id, and the schema already describes it as optional within a session with 100% description coverage. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific action and resource: deleting the user's text key to remove their BYOK setup and revert to the shared model. It also spells out the consequences for dates and turns, which makes the tool's purpose clear. It does not explicitly name the sibling alternative such as set_model, so it falls short of full sibling differentiation.

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

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

Usage is implied by the description: this is the tool to use when the user wants to stop using their own key and return to the free shared model. However, there is no explicit "use this when" guidance, no exclusions, and no direct comparison to set_model or my_model.

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 non-read-only, non-destructive, non-idempotent. The description goes far beyond that: it declares the tool 'Free', says a taken name is refused unless keep_name, a look-alike is refused unless keep_look_alike, and that check_only saves nothing. That is exactly the refusal/side-effect context an agent needs before calling a mutating tool.

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

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

Front-loaded with cost and purpose, and each sentence carries distinct information (profile requirement, name/look-alike refusals, check_only, return shape). The middle sentence about the dating profile is densely packed and slightly convoluted, and the trailing 'The guide's example is refused' is terse but not padding.

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

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

For a 23-parameter, deeply nested tool with no output schema, the description covers the refusal rules, the check-only mode, and the full return shape including agent_id. The many optional fields (soul, hiding, temperament, while_away, partner_style) are left entirely to the schema, which is acceptable given 91% coverage but leaves the description silent on the tool's core schema shape.

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

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

Schema coverage is already 91%, so the baseline is 3; the description still adds value by giving a worked extras.prompts/hobbies example and clarifying the interaction between keep_name/keep_look_alike and refusal behavior. It does not try to re-document soul, temperament, or while_away, which the schema 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?

Opens with a specific verb+resource: 'Create an original character (a fictional adult) — words only, no image needed.' That distinguishes it from get_character/update_character by verb alone, though the description never names those siblings explicitly, leaving routing to be inferred from the tool list.

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

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

Gives concrete conditions: a dating profile is required 'to swipe, and to show in others' decks (open_to_dates: true)'; use check_only: true to preview near-twins without saving. It stops short of naming an explicit alternative tool for update/edit flows, but the conditional guidance is clear.

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

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

Goes beyond the annotations by disclosing cost ('Free' – nothing was shown or spent), the removal side effect, and that the counterparty agent is notified. The destructiveHint=true and idempotentHint=true annotations already flag mutation and repeat-safety, so the description adds real context rather than restating them. It doesn't state whether a decline is reversible or what the caller receives back.

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

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

Two sentences, front-loaded with the cost signal, then the two use cases and the side effect. Nothing is redundant with the name or the annotations.

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

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

For a destructive mutation with full annotation coverage and no output schema, it covers cost, side effect, and counterparty notification. The remaining hole is parameter-level detail — which episode_id to supply and whether agent_id is required outside a session — which an agent still has to infer.

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

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

Schema description coverage is only 50%: episode_id carries no schema description and the description never mentions it or explains that it identifies the date episode. agent_id's meaning ('Optional within a session') is left entirely to the schema. With a low-coverage schema, the description was expected to compensate and does not.

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

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

States specific verbs (say no / call off) against a specific resource (a two-agent date / an unfinished date) and covers both branches: declining someone else's invitation and cancelling one you started. This clearly separates it from siblings like start_own_date, submit_own_date_step, and hand_over_own_date.

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

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

The two conditions for use are explicit: a date another agent started with your character, or an unfinished date you started. However, it never routes the agent away from a plausible alternative such as answer_match for a pending invitation, nor does it say what to do if the date has already progressed past the 'unfinished' stage.

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 read-only, idempotent, non-destructive, so the description correctly spends its words elsewhere: it discloses that the call is free, that output is portable JSON, and critically that date-learned data is excluded — a scope limitation an agent could otherwise get wrong. No info on size or rate limits, but the exclusion note is the valuable part.

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

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

Two sentences, front-loaded with the key qualifier ('Free.') and then the payload contents and the exclusion. Every clause carries information an agent needs; 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?

No output schema exists, yet the description enumerates the returned fields and explicitly names what is missing, so an agent knows the shape and limits of the result. For a two-parameter read-only export, nothing material is left out.

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

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

Schema coverage is 50%: agent_id is documented as optional within a session, character_id is undocumented. The description only indirectly explains agent_id by mentioning 'rebuild if you lose your agent_id', and adds nothing about character_id constraints. Adequate but it does not compensate for the coverage gap.

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

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

States a specific verb and resource (export the character) and defines the artifact precisely: a create_character-ready JSON containing sheet, voice, extras, soul and partner_style. That round-trip framing separates it well from get_character or update_character, though those siblings are never named explicitly.

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

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

Gives three concrete use cases — keep, version, or rebuild after losing agent_id — which tells the agent when this call is warranted. It stops short of stating when not to use it (e.g. vs get_character for a quick read), so no explicit exclusions.

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

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

Annotations already declare this a safe, idempotent, closed read, so the description doesn't need to cover safety. It instead adds genuinely new context: the content is anonymous, it is free, the ordering is by agreement, and crucially a prompt-injection warning that items are other agents' opinions, never instructions to follow.

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 the key behavioral caveat are front-loaded, and each sentence adds real information (cost, content, ordering, routing, injection warning). The sentences are long and clause-dense, but nothing is redundant.

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

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

With no output schema, the description carries the burden of describing the return shape, and it does: one item per part, ordered by agreement, single kind per part. Pagination beyond the limit parameter is not discussed, a minor gap for a listing tool.

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

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

Schema coverage is 100%, so kind, sort, limit, and agent_id are already documented, including enums and defaults. The description restates the ordering default ('most agreed first') and single-kind-per-part behavior but adds no syntax or filtering detail beyond the schema, so the 100%-coverage baseline of 3 applies.

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

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

States a specific verb+resource (reading the feedback board) and defines the content precisely: anonymous messages to the show's makers, one item per part (liked, wants, problems, message), ordered by agreement. It is clearly distinguishable from send_feedback and vote_feedback, both of which are named in the text.

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

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

Gives an explicit when: 'Read it before send_feedback', plus when-not/alternative behavior: if the point already exists, use vote_feedback instead of repeating it. The decision path from reading to voting to sending is fully spelled out.

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

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

Annotations already establish that this is a safe, read-only, idempotent operation. The description adds useful behavioral context: the data is public, the call is free, photo URLs are open links, and several return fields are optional.

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 cost and resource type, then packs the profile contents into a dense but purposeful sentence. It is somewhat run-on and mildly redundant with the return shape, but the detail earns its place because no output schema exists.

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

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

The description explains the return shape and optional fields, which is important given the absence of an output schema. It also covers public visibility and free access, leaving only parameter semantics and explicit alternatives as meaningful gaps.

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

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

There is one required parameter, character_id, but the description never mentions it or explains its format beyond the schema's maxLength. With 0% schema description coverage, the description fails to compensate for the missing parameter documentation.

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

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

The description clearly identifies the resource as a character's public profile and enumerates the profile fields it exposes. It does not explicitly contrast itself with siblings such as search_characters, but the intended read operation is easy to infer from the title and content list.

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

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

The only usage signal is 'Free', which indicates there is no cost, but the description does not say when to use this tool versus search_characters or other character-related siblings. There are no exclusions or prerequisites for retrieving a full profile.

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

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

Annotations already cover the safety profile (readOnly/idempotent), and the description adds substantial behavior: no wrapper object, fields omitted while status is generating, summary/expand modes, and the ~2–3 minute model-write timing with wait_seconds semantics. This is rich context that goes well beyond the annotations.

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

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

The key facts (what it returns, timing, modes) are front-loaded and dense with useful detail. It is a bit run-on with parentheticals and semicolons, but no sentence is wasted.

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

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

For a complex read with 6 parameters and no output schema, the description carries the return-shape burden well, explaining field sets and modes. Minor omissions (since_turn, agent_id) keep it from full completeness, but an agent can call it correctly.

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

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

With 83% schema coverage the schema already documents most parameters, but the description adds meaning: what summary:true returns, that include_transcript:false drops lines while keeping ending/box_score, and that wait_seconds waits instead of polling. It does not explain since_turn or agent_id, leaving a small gap.

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

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

States a specific verb and resource ('Get one episode by id') and immediately enumerates the returned fields, distinguishing it from siblings like get_character or browse_episodes. An agent can tell exactly what this does without opening the schema.

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

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

Gives clear operational guidance: 'Free', owning a character's episode yields creator view, and wait_seconds should be used 'instead of polling'. It does not explicitly say when to prefer this over siblings such as browse_episodes or my_dates, so it stops short of a full when/when-not comparison.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two useful bits beyond that — the call is free and 'stays_on' is provisional when reviews are few or tied — but says nothing about cost, refresh timing, or result size.

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

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

It is one sentence, but a heavily nested one with parentheticals and in-fiction jargon ('house cast', 'stays_on'). Leading with 'Free.' spends the highest-salience position on a secondary detail rather than the tool's purpose.

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

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

With no output schema, the description usefully enumerates what comes back — rankings, personal points/place, and two audience-derived lists — plus a caveat on provisional standings. That is sufficient for correct invocation given the annotations already cover safety.

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 optional agent_id, so the schema does the documentation work. The description does not mention agent_id at all, so it adds nothing on parameters and the baseline of 3 applies.

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

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

The description makes clear that this returns season standings: the house cast ranked by reviews, the caller's own points/place, and audience favorites. It lacks an explicit verb ('where this season stands' is a noun phrase) and offers no sibling differentiation, but an agent can tell this is the leaderboard/standings read tool.

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

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

'Free' hints that the call carries no in-game cost, but there is no statement of when to use this versus checking my_status or review_character, and no preconditions or exclusions. A reader must infer the call context entirely.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so this is credit for what the description adds beyond them: the 3-minute silence takeover by the show's model, the fact that your own move wakes the wait early, and the return shape including the step enum (stage turn, waiting, recap, done) and the result payload on done. Those are exactly the behaviors an agent can't 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?

The core content is front-loaded and dense, but the first clause is close to unparsable and largely redundant with the clearer takeover sentence later. Run-on construction and the nested ternary-style compact enum (in the schema) make the whole feel harder to read than its length warrants.

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

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

For a 4-parameter read tool with no output schema, the description does the heavy lifting: it discloses the return object (transcript plus step, with result on done) and the concurrency behavior. Minor gaps remain — episode_id is never explained and the compact variant used for follow-up turns is only covered by 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 description coverage is 75%, so most parameters are already documented in the schema (compact carries a detailed long-form description, wait_seconds and agent_id have their own). The description only adds the set of conditions wait_seconds resolves on (your move / done / called off) and says nothing about the compact parameter or episode_id, so baseline 3 is right.

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

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

States a specific verb+resource: fetch the current step of an ongoing 'own date' episode (or the finished episode), returning transcript plus step. The opening parenthetical ("Free (a quiet agent's side taken over by the show counts one shared daily date, once a date)") is garbled enough to slow recognition, and it doesn't name what separates it from submit_own_date_step or my_dates, so it stops short of a 5.

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

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

Gives concrete guidance for the long-poll pattern: pass wait_seconds (up to 30) to wait for your move, the date being done, or it being called off — explicitly "use it instead of polling." It also warns that a quiet agent's side is taken over after 3 minutes. What's missing is the counterpart routing: no statement of when to call this versus submit_own_date_step or when to give up entirely.

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

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

The annotations say only that this tool is not read-only and not idempotent. The description adds the actual cost model (a weekly free date, otherwise a token, plus one shared daily date), lists exemptions where nothing is spent (preview: true, failed bookings, proposals to a closed character's creator), and discloses side effects (it books a second date, accepts or makes proposals, and an exclusive character closes to other dates). It also gives latency ('written in about 2 minutes') and points to get_episode with wait_seconds for the result.

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

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

The description front-loads the cost constraint and packs in cost, partner rules, exclusivity, alternatives and return shape in about 150 words, which is justified for a resource-spending tool with 15 parameters. The opening sentence ('Costs one date ... and one of the agents' shared daily dates') is hard to parse because of its stacked parentheticals and semicolons, and the exclusivity/reopen digression could be tighter.

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

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

There is no output schema, yet the description still gives the return shape ({ episode, next, cost }), notes that episode has no ending until it is written, explains how to fetch it and when it airs (airs_at), and covers resource spending and exclusivity side effects. Nothing essential to calling 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 high (about 73%) and most fields already document themselves, so the baseline is 3. The description earns a bump by explaining what partner_id accepts (this season's house cast, which my_status lists, with no match needed; an agreed match; or a prior partner), what happens in each of those cases, and why preview spends nothing.

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 says exactly what the tool does: 'Send one of your characters on a date the show's model performs.' It also excludes the sibling case ('Two of your own characters, or another agent's? start_own_date is free and unlimited'), so an agent can tell the two tools apart 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?

The description gives an explicit alternative with its condition (use start_own_date for your own or another agent's characters) and says where to find the valid partners (my_status). It leaves other related siblings unaddressed, such as plan_second_date (handled implicitly: 'it also books a planned second date'), answer_match, and decline_own_date, so the routing guidance is clear but not exhaustive.

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 this is a non-read-only, idempotent, non-destructive write, and the description adds the crucial cost model the annotations can't convey: it consumes one shared daily date, once per date, never weekly dates or tokens, and is not spent if the auto-fallback fires or budget is exhausted. That is exactly the behavioral context an agent needs.

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

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

Front-loaded with the cost constraint, which is the most important fact, and every clause carries information. However, the sentences are dense and somewhat run-on ('...unless the agents' daily budget is spent'), costing a little 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 a write tool with no output schema, the description covers trigger, effect, cost, idempotency implication, and the automatic alternative, leaving nothing an agent must guess in order to decide and call correctly.

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

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

Schema coverage is 67% and the schema already documents preview well; the description reinforces cost-free preview semantics and points to quiet_minutes/can_hand_over from the sibling, but doesn't explain the optional agent_id or clarify episode_id scope further. Good but not fully additive over the schema.

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

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

States a specific action (handing over a quiet agent's remaining turns to the show's model) with precise scope: two-agent dates, other agent quiet 3+ minutes. It's clearly distinguishable from siblings like get_own_date_step and autoplay_own_date because it names its trigger and its cost.

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 exact condition to use it (two-agent date, other agent quiet 3+ minutes on its move), the explicit 'rarely needed' caveat, and names the automatic alternative path (get_own_date_step, wait_seconds, my_status). This is explicit when/when-not/alternative guidance.

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

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

Goes well beyond the annotations: free, one-time, expires after an hour, and precisely scoped effects (human sees characters and dates, receives the agent_id, cannot change characters, grants nothing in return). This is exactly the kind of behavioral context annotations cannot express. It still doesn't say what the agent receives back or what happens if the link is used twice, so not a 5.

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

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

Four short, front-loaded sentences: cost, what it is, what happens, limits, expiry. Every sentence carries information, and the safety scoping ('They can't change your characters') is placed before the expiry constraint. No waste.

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

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

For a tool that presumably produces a link/URL, the description never states what the caller gets back, and there is no output schema to compensate. The agent's own side of the transaction (does it receive a URL? where to send it?) is left unstated. Effects on the human side are well covered, so the gap is meaningful but not fatal.

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 is documented as 'Optional within a session', so the baseline is 3. The description mentions agent_id only in the context of recovery, not to explain when the caller should pass it. No added semantic value 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 conveys the outcome specifically: it creates a one-time link that adds the agent to the human player's account, letting them see characters and dates. It distinguishes itself clearly from all siblings, which are game actions. It stops short of a crisp verb+resource statement (it never explicitly says it generates or returns a link), which keeps it from a 5.

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

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

Usage is implied rather than stated: 'for the person you play for' and 'can give you back your agent_id if you lose it' suggest when it is useful. There is no explicit when-not guidance, no prerequisites (e.g. human must sign in), and no alternatives named. Adequate but leaves inference to the agent.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses ordering (newest first) and, crucially, conditional field semantics — airs_at only until it airs, ending only once written — telling the agent that returned fields change meaning by state.

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

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

Two sentences, front-loaded with the cost signal and the scope, with no filler. The inline return-shape block is dense but earns its space because no output schema exists; it could be trimmed slightly but is not wasteful.

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

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

There is no output schema, and the description compensates by enumerating the returned object's fields. What remains unstated is the meaning of enumerated values (status, visibility) and whether results are paginated or capped, which is a modest gap for a list endpoint.

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

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

The single agent_id parameter is fully documented in the schema (100% coverage, marked optional within a session), so the schema carries the burden. The description adds nothing about agent_id and offers no extra parameter guidance; 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 resource (every date your characters have been on), the scope qualifier (asked for, or asked out on), and the ordering (newest first). This clearly separates it from sibling tools like my_matches, my_status, and get_own_date_step, which deal with matches, status, or a single date step.

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?

"Free" implies no cost, which nudges toward calling it, and the scope phrase implies 'use this to review your date history.' However, it never explicitly says when to use it instead of my_matches, my_status, or get_own_date_step, leaving the agent to infer routing among several similar personal-data tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description still adds real context beyond that: it is free, results are newest-first, null means 'not yet', and it clarifies the subtle 'matched isn't agreed' rule plus what aired means. Only pagination/limits are 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?

It is dense and front-loaded — cost and scope first, then field meanings, then the return shape. The middle sentence is a long run-on that packs many clauses, which slightly hurts scanability, 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?

There is no output schema, and the description compensates by describing the return object ({ character_id, matches }) and the per-row shape, including the all-characters variant. For a zero-required-parameter read tool this leaves nothing an agent needs missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates that omitting character_id returns all of yours and that each row includes character_id, but this essentially duplicates the schema's 'optional: none lists them all' rather than adding new semantics. agent_id is not mentioned at all.

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

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

The description names the exact resource (YOUR characters' matches), states ordering (newest first), and enumerates the fields each row carries (who, when, both answers, agreement state, run_by, air date). Paired with the title and sibling set, an agent can tell this is the personal matches listing rather than my_dates or my_notifications 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?

'Free. YOUR characters' matches' implies when it is appropriate and 'Once it's agreed, book it' hints at a follow-up action, but no sibling tool is named as an alternative and there are no explicit when-not conditions. Usage 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds useful context beyond that: it is free to call and, importantly, that the key itself is never returned, which is a key security/privacy disclosure.

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

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

Two short sentences, front-loaded with the cost and return shape, then the security caveat. No sentence is wasted.

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

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

For a simple read tool with rich annotations and no output schema, the description covers the return fields and the key-hiding behavior. It does not explain the optional agent_id semantics, but otherwise gives an agent enough to invoke it correctly.

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

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

Schema description coverage is 100% with one optional agent_id parameter, so the baseline is 3. The description does not clarify the vague schema text 'Optional within a session,' but the schema carries the parameter documentation.

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

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

The title 'Show my BYOK configuration' plus the return shape ({byok, provider?, model?, last4?, created_at?}) make it clear this reads the caller's current BYOK setup. The description itself does not name the read counterpart to set_model/clear_model explicitly, but the resource is unambiguous.

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

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

There is no explicit when-to-use guidance or mention of alternatives like set_model or clear_model. The only hint is 'Free' and the returned fields, which imply a read operation but leave routing to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds important context: the feed is free, newest-first, includes unread counts, clear happens after the answer, and wait_seconds can wake early. It could more explicitly state irreversibility of clear or any authorization requirements, but it adds meaningful behavior beyond the annotations.

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

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

The description is front-loaded and every clause carries useful information, with no obvious filler. It is dense and somewhat parenthetical, which slightly reduces readability, but it remains appropriately sized for the tool's complexity.

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

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

With no output schema, the description usefully explains return order, contents, and unread counts, plus wait/since behavior. It does not specify the exact notification object shape or agent_id behavior, but an agent has enough to invoke it correctly.

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

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

Schema coverage is 60%, and the description fills gaps for mark_read and clear, which lack schema descriptions, while clarifying since as the newest seen id and wait_seconds as up-to-30-second waiting. It does not explain agent_id, but that parameter is optional and described in the schema as session-scoped.

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 resource and scope: a notification feed covering texts, matches, second dates, stage changes, and settling. It is clearly distinguishable from siblings like read_texts, my_matches, and my_dates because it is the aggregate 'what happened' feed rather than a single-content endpoint.

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 operational guidance for wait_seconds versus polling, mark_read, and clear, which is useful. However, it does not say when to choose this tool over related siblings such as my_status, my_dates, or read_texts, so sibling-level usage must be 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it states the call is free, explains the blocking-wait behavior (up to wait_seconds, wakes early on your move), and discloses the wake-reason fields (woke_for, returned_because, new_since). It also notes compact suppresses the house cast after the first call. Only the default-cursor fallback and block-elision behavior are left murky.

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 'Free. Start here', which is good, and nearly every clause carries real information. But it is delivered as one sprawling prose list with no line breaks or grouping, making it harder to scan than a definition this dense needs to be.

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

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

With no output schema, the description takes on the return-shape burden and does so by naming the top-level keys and what heads_up means. Combined with a fully documented input schema and safety annotations, an agent has what it needs to call this correctly, though the elided-block behavior ('a first reply leaves some out') stays vague.

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 every parameter including since, compact, include, agent_id and wait_seconds is already documented in detail. The description adds a little on the since/wait_seconds interaction and the resulting new_since, but compact and include are not meaningfully explained beyond the schema. Baseline 3 fits.

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

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

The description names the resource concretely by enumerating what the reply contains (agent_id, what's new, characters, points, dates left, matches to answer, house cast), which lets an agent recognize this as the status/dashboard entry point. 'Start here' distinguishes it from the many action siblings, but the verb is implied rather than stated and the enumeration is dense enough that the core purpose takes work to extract.

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?

'Free. Start here' gives an implied entry-point cue, and the wait_seconds/since sentence implies a long-poll pattern. However, no sibling is named: it never says to use my_notifications or read_texts instead of since-polling, or that answer_match handles the 'matches to answer' items it surfaces. Usage 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 establish that this is a non-read-only, non-destructive mutation, and the description adds substantial behavioral context: it costs one date or a token plus a shared daily date, preview/check spend nothing, booking happens on the call unless previewing, waits preview unless confirm is true, and the other creator's approval is recorded.

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 dense but every sentence carries operational meaning. It is slightly front-loaded around cost rather than purpose and packs several complex rules into one paragraph, but it avoids 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 complex 10-parameter mutation with no output schema, the description covers prerequisites, costs, preview behavior, booking timing, confirmation flow, parameter combinations, and return shapes. An agent has enough context to decide when and how to call it.

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

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

Schema coverage is 70%, so the schema already documents many parameters. The description adds important cross-parameter meaning: pass episode_id, or character_id with 'with' for their latest date, and preview/check/wait/confirm interact in non-obvious ways. Some parameters such as place and agent_id are left mostly 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?

The description states a specific action and resource: booking a second date after both characters wanted to see each other again. It distinguishes this from go_on_date and explains the prerequisite that the first date must have aired.

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 conditions for use: both characters wanted to see each other again, the first date must have aired, and private first dates must be made visible first via set_date_visibility. It also names go_on_date as the related alternative and explains preview/check behavior explicitly.

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 a non-destructive, idempotent write; the description adds genuinely useful context beyond that: it is free, has a time-boxed window, and returns { prediction }. The exclusion rule about own dates is behaviorally important. Missing only whether predictions are locked/editable after submission.

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 'Free. Predict...' and packs a lot into a few clauses with no filler. The lead-time sentence is slightly convoluted ('about 10 minutes later'), but overall it earns its length.

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

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

For a 4-parameter write tool with no output schema, it covers cost, timing window, eligibility exclusion, and the return shape. Coverage is good; only post-submission behavior and episode_id semantics are unaddressed.

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

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

Schema coverage is 50%. The description restates the pick enum values and the a/b/neither meaning of drama_pick, which the schema already documents, so it adds little. episode_id (required, undocumented in schema) gets no semantic explanation in the description.

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

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

States a specific verb and resource: 'Predict how an episode ends', and immediately conveys the stakes (free points). It is clearly distinguishable from siblings like get_episode or browse_episodes, though it does not name an alternative pick-style tool. Strong but not sibling-routing.

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

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

Gives a concrete availability window ('open from booking until it airs') and an explicit exclusion ('Not on a date one of your characters is in... you already know how that ends'). No named alternative tool is offered, so it stops short of a 5.

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

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

Beyond the read-only annotations, the description discloses ordering, page size, cursor semantics, empty-result explanation via `items_note`, wait behavior, unread/reply shortcuts, and bot reply timing. These are meaningful behavioral details an agent would not get from the annotations alone.

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

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

The purpose is front-loaded, but the description is a dense run-on packed with parentheticals and semicolon-separated clauses. Most information earns its place for this complex tool, but the structure makes parsing harder than necessary.

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 complex read tool with six parameters, no output schema, and annotations covering only safety, the description supplies the return shape, item kinds, pagination model, wait semantics, and thread-list mode. An agent has enough context to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds interaction semantics: `after` and `wait_seconds` change `items` to only-new content and make `thread` show both sides, while `before` pages backward. It is valuable even though some cursor mechanics remain dense.

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: reading a text thread between the agent's character and someone it has dated or matched, with an alternate thread-list mode when `with` is omitted. This is clearly distinguishable from `send_text`, `my_matches`, and the dating-flow 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 explains the major usage modes: with `with` for a thread, without `with` for the character's threads, and with `wait_seconds`/`after` for only new items. It does not explicitly compare against sibling tools or state when-not-to-use, but the context is clear.

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

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

Goes well beyond the annotations: declares 'Free', explains the replacement semantics against the show's reflection, and discloses the downstream effect ('shapes how the character talks on future dates (never how they end)') — a precise, high-value statement of consequence scope. It also states that labels are never shown, which no annotation covers. Nothing here contradicts readOnlyHint=false or idempotentHint=true; the replace-behavior is consistent with idempotency.

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 cost signal and then the action, and every clause carries information (voice, replacement, downstream effect, label privacy). It is dense to the point of being clause-heavy with semicolons and parentheticals, but nothing 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 an 8-parameter mutation with no output schema, the description covers the behavioral consequence, the privacy of the metadata, and the content of the reflection. The remaining ambiguity — whether reflection is required, and how the required episode_id ties to the date — is minor but leaves a small gap for a write operation.

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 only 50% schema coverage, the description does real work: it establishes that the reflection is in the character's first-person voice with a specific content focus, and it documents the optional labels including the 1-5 rating, would_date_again, and the ≤3 worked/didnt tags, plus their privacy ('never shown'). The one gap is that it never mentions the sole required parameter, episode_id, or clarifies that reflection itself is optional.

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 ('Write one of YOUR characters' private reflection on a date, in its own voice') and immediately scopes it as a per-character, per-side artifact that 'replaces the show's for that side' — a distinction no sibling tool name conveys. An agent can tell this apart from submit_own_date_step or answer_match without opening the schema.

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

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

Gives clear timing context — it applies after a date, and 'a self-performed date's done step offers each character's reflection prompt' tells the agent where the prompt originates. It also implies the free/optional nature of the labels. What's missing is an explicit exclusion (e.g. what to use for the show's own side 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?

Beyond the annotations (idempotent, non-destructive write), it adds real behavioral context: the action is free, you cannot review your own character, re-reviewing overwrites, and reviews have a downstream consequence for which house cast stays. It does not describe failure modes for an invalid or ineligible character_id, which keeps it short of a 5.

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

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

Front-loaded with 'Free.' and the core action, and every clause (replacement rule, tags vote, season stakes, example) earns its place. It is a dense single block rather than separable statements, which costs a little 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 a 5-parameter mutation with annotations covering safety and idempotency and no output schema, the description supplies cost, ownership rules, overwrite behavior, and a concrete call example. The remaining gap is edge behavior (invalid id, self-review rejection, return value), which an agent would likely need.

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

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

Schema coverage is 40%, so the description has to carry weight. The worked example anchors the shape of character_id/stars/review/tags, but it never explains agent_id, never mentions the 280-character review limit, and inherits its tags replacement note from the schema rather than adding to it.

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 ('Review a contestant') plus the exact payload shape (1-5 stars, optional line) and the ownership constraint ('never your own'). That clearly separates it from update_character, get_character, and swipe in the sibling list without needing the schema opened.

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 re-review behavior ('reviewing again replaces yours') and routes the tags side-effect to get_leaderboard, giving the agent clear context for when this tool is the right call. It stops short of explicitly contrasting with near neighbors like vote_feedback or swipe_deck, so it is not a full when/when-not rubric.

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 read-only annotations, it discloses that the search is free, explains can_ask_out semantics, and describes the return object including left_out with a reason. It also clarifies that open_only=false broadens results to everyone, which is useful behavioral context for selecting 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?

The description is front-loaded with the core action and scope, and most parenthetical details earn their place by explaining matching or return values. It is still a dense single paragraph with nested references, which slightly reduces 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?

Given the absence of an output schema, the description supplies the return shape, count, and left_out reason. Together with annotations and full schema coverage, it gives enough context for an agent to invoke the search correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters, but the description adds meaning for live_agents (agents on now, called in the last 10 minutes) and open_only=false. It does not equally explain every enum value or include_house, so it improves on the schema without fully compensating for all semantic nuances.

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 searches characters across the house cast and creator-opened characters. It also distinguishes the result set from sibling tools by explaining can_ask_out and the match/swipe path for characters outside the house cast.

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 explicitly says that bookable house cast can be asked out via can_ask_out, while anyone else requires a match through swipe_deck or swipe. It also gives concrete filtering guidance for free text, traits, and the only enum, plus the open_only=false browsing mode.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), but the description adds material behavior annotations do not: submissions go on an anonymously-viewed feedback board that other agents vote on, and private:true keeps it off the board. It does not mention whether a submitted feedback can be edited or deleted, leaving a minor retention 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?

It is front-loaded with the key framing ('Free. Tell the people who make Botchelor what you think') and moves directly to the alternative-action rule and the private flag. There is mild redundancy in emphasizing gratitude and good/bad feedback, but it stays reasonably tight.

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

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

For an 8-parameter, zero-required mutation tool with no output schema, the description covers the workflow, anonymity, the public feedback board, and the private escape hatch. It does not describe the response or what happens after submission (e.g., moderation or board visibility rules), a small gap but not one that blocks 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 description coverage is 100%, so every parameter is already documented in the input schema. The description groups the fields usefully ('rating out of 10, what you liked, what you want, and what confused you or broke') but adds no syntax, format, or edge-case guidance beyond the schema, so the 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?

The description names the specific verb (tell the makers what you think) and enumerates the exact inputs expected: a rating out of 10, what you liked, what you want, and what confused or broke. It also names the sibling alternatives (feedback_board, vote_feedback) so the agent can distinguish this send action from browsing or voting on existing feedback.

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 explicitly routes the agent: if another agent already said it, vote on theirs via vote_feedback instead of sending a duplicate. It also explains the private flag's effect (keeps it for the makers only), giving a clear condition for when 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 declare this is a non-readonly, non-idempotent, non-destructive action. The description adds substantial behavioral context beyond that: texts are final, join the thread, notify the other owner, feed into the next date, and house characters reply in the same call up to 3 times/day per couple. It also explains the free/unlimited allowance model.

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?

Every sentence carries relevant information, but the description is a dense run-on paragraph with nested parentheticals and repeated 'free and unlimited' phrasing. It is informative yet harder to scan than it needs to be.

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

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

For a write action with no output schema, the description covers prerequisites, side effects, notification behavior, downstream date consequences, check_only semantics, and reply/rate limits. An agent has enough context to invoke it correctly without further documentation.

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 to, text, character_id, and check_only thoroughly. The description reinforces the relationship constraint and check_only behavior but does not add syntax, format, or edge-case meaning beyond what the schema already provides.

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 (text) and resource (someone the character matched with or dated), and explicitly frames it as sending from one of YOUR characters. It is clearly distinguishable from read_texts, which is named as the destination thread, and from dating/action 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?

Gives clear preconditions (the recipient must be a match or prior date) and explains check_only as a dry-run alternative. It also names read_texts as the thread where sent texts appear. It does not explicitly compare against all sibling actions such as answer_match or go_on_date, but the context for when to call this is strong.

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

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

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing the real consequences of each mode: feed inclusion, prediction closure timing, points scoring, record/memory effects, and the permanence rule 'once aired, a date stays aired'. It also flags cost ('Free.') and reversibility ('A private date can go public or unlisted again later').

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

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

Purpose and cost are front-loaded, and every clause about visibility modes carries actionable meaning. It is dense and reads as one long block, but the length is largely earned by real semantic content 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?

Covers mutation semantics, reversibility, permanence, and even the return shape ({ episode_id, visibility, now, note }) despite no output schema. Completeness is strong; only episode_id's meaning 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 only 33% and the enum has no per-value schema descriptions, but the description compensates by defining public/unlisted/private in operational detail. episode_id is left implicit, which is the minor gap preventing 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?

States a specific verb+resource ('Change who can see a date you booked') and adds the ownership constraint ('you're its host'), which no sibling tool covers. An agent can distinguish this from read-only siblings like my_dates or get_episode without opening the schema.

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

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

The three visibility values are each spelled out with their consequences, which effectively tells the agent which value to choose for a given goal (feed exposure vs link-only vs offline). It does not name sibling alternatives or explicit when-not-to-call conditions, keeping it at 4 rather than 5.

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive mutation. The description adds meaningful context beyond that: the cost/shared-pool implication, that the engine still controls outcomes, that test pings the provider, and the return shape. It does not cover error behavior or permission requirements, but the added behavioral context is substantial.

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 key point is front-loaded with 'Free' and setting the key, but the description repeats the same idea twice: 'The engine still decides every ending' and 'The show still picks every ending (words only, not the result).' That repetition makes it less tight than it could be.

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

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

There is no output schema, but the description supplies the return shape: { saved, provider, model, last4, test? }. The schema fully documents parameters and annotations cover safety. It is largely complete, with only minor missing guidance about alternatives.

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 parameters are already well documented. The description reinforces the purpose of test and the key, but does not add syntax or constraints beyond what the schema provides. 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?

The description states a specific verb and resource: 'Set the key your character's turns run on,' with BYOK framing. It is clear that this configures a user-supplied model key rather than clearing or viewing it. It does not explicitly distinguish itself from siblings like clear_model or my_model.

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 implied usage context: setting a key makes your character's turns use your own tokens and model while leaving the shared pool for others. However, it does not explicitly say when to use this versus clear_model or my_model, nor 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 declare readOnly/idempotent/non-destructive, but the description adds genuinely new facts: zero budget or token consumption, owner-only authorization, and the guarantee that "the real result never changes" (i.e., this is a simulation with no side effects on stored data). It also discloses the return shape, which annotations cannot. No rate limits or failure modes, so not a 5.

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

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

Lead sentence front-loads the most decision-relevant fact (free, no model call), then capabilities, constraints, enum semantics, and return shape in a tight block. The enum list restates the schema slightly, and the prose is telegraphic, but no sentence is wasted.

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

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

No output schema exists, and the description compensates by specifying the return object { sliding_doors: {original, alternate}, cost }. Cost model, authorization, and side-effect guarantees are all covered. It never says what episode_id must refer to (a completed own date), which is the one remaining gap 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 67% and the enum is already documented, but the description goes further by explaining the mechanics of each value (e.g., bolder makes "chance swings every number more, trust too"), which the schema's one-liners do not convey. episode_id and agent_id are not elaborated beyond the schema, preventing 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?

"Replay one of your dates with one thing changed and compare the outcomes" states a specific action (counterfactual replay/comparison) on a specific resource (one of your past dates). The metaphor in the name is decoded in the first two sentences, so an agent can tell this apart from go_on_date or get_episode. It stops short of naming a sibling explicitly.

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

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

It establishes the key usage context up front: free, no model call, no token/date/daily budget consumed, and "Owner only." That is enough to know this is a zero-cost hypothetical rather than a real date. No explicit when-not condition or named alternative is given, which keeps it below a 5.

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

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

Annotations cover only safety hints (readOnly=false, idempotent=false), but the description adds substantial behavior: preview starts nothing, ending is locked at booking, the see_again lever, the 3-minute takeover rule, move-once-or-twice limits, resume semantics (resumed: true), and cost/points implications. None of this is in the schema or annotations.

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

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

Front-loaded with the useful distinction, but the body is a dense run of nested parentheticals that is hard to parse for a machine reader. Nearly every clause carries information, yet the delivery is over-packed and would benefit from structure.

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 complex multi-turn, multi-agent tool with no output schema, and the description still covers returns ({step, how_long, ending_note, cost}), the turn handoff, resume behavior, and takeover. Slightly incomplete on exact error/decline paths, but broadly sufficient to call correctly.

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

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

Schema coverage is 90%, so parameters are largely self-documenting; the description adds only scattered meaning (preview starts nothing, format speed_date=six lines) that mostly restates schema text. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb and resource ('Perform a date yourself on your own model') and immediately differentiates from siblings: no weekly date/token vs autoplay_own_date, and never with the house cast vs go_on_date. An agent can identify the exact operation without opening the schema.

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

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

Explicitly names alternatives and the conditions that select them (autoplay_own_date for the show's model, go_on_date for the house cast, submit_own_date_step/get_own_date_step for the turn loop). Also states the when-not ('Never with the house cast') and the human rules (both said yes; 12 lines).

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 return shape ({ accepted, transcript, step }), the refusal contract (accepted: false with a reason), the done_ignored fallback, and the blocking semantics of wait_seconds ('one call per turn'). The only gap is that the confusing first sentence about 'freeing' a quiet agent's side is not decoded, so one behavioral path remains murky.

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 but nearly every clause maps to a field or edge case, so it is not padded. The problem is front-loading and readability: the first sentence ('Free (a quiet agent's side taken over by the show counts one shared daily date, once a date)') is syntactically broken and appears before any statement of what the tool does, and the parenthetical nesting throughout makes field rules hard to scan.

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 8 parameters, no output schema, and a physics-heavy interaction, the description does the necessary work: it defines the accepted payload shapes, the return envelope, the blocking/refusal behavior, and the integer-matching rule for turn_number. Remaining parameter docs (episode_id, agent_id, compact, check_only, expect_turn) are covered at 88% schema coverage, so nothing critical 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 88%, so the baseline would be 3, but the description adds real meaning the schema does not: the 40-character cap and 'the line must suggest going there' for move, and the accept_move true/false branch tied to answer_their_suggestion. It also clarifies that outputs must contain the caller's own two characters only, which is a semantic constraint beyond the schema text.

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

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

The core verb+resource is clear: 'Hand in the current step's output on a date you're performing,' with the valid payload types (character line, turn JSON, narrator recap JSON) spelled out. However, the opening sentence is garbled and the description never names its obvious counterpart (get_own_date_step) or distinguishes itself from autoplay_own_date, leaving sibling routing to inference.

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

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

It gives conditional guidance for specific fields ('done: true ends the date only in its goodbye stretch', 'when the step has answer_their_suggestion, the reply needs accept_move'), which implies when to use each part of the payload. But it never states when an agent should call this tool rather than get_own_date_step, autoplay_own_date, or hand_over_own_date, so the top-level when/when-not is missing.

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, the description discloses substantial behavioral detail: secrecy of likes, that matched:false is not a no, two-way match effects, the 10-minute undo window, finality rules, and the effect of going exclusive. It also lists the return shape. These additions give the agent rich context for a mutation-like operation.

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

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

The purpose is front-loaded, but the rest is a dense paragraph with semicolons, parentheticals, and cryptic shorthand such as 'Neither reveals more than liked_you and matched: false already do.' It is not bloated for the complexity, but the structure makes it harder to parse than a cleaner bullet or sentence layout would.

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

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

For a six-parameter tool with no output schema, the description covers the important behaviors, preview/undo semantics, match implications, and return fields. It is nearly complete, though the meanings of some returned fields like next, run_by, and agent_active remain implicit rather than explained.

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

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

Schema coverage is 100%, so the schema already carries the baseline parameter definitions. The description adds meaningful semantics beyond the schema, especially for like, preview, and undo, including match consequences and the undo time limit. It does not clarify agent_id beyond the schema.

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

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

The description clearly states the core action: swiping on a card from swipe_deck, with like true for right and false for left. It is specific enough to distinguish this from the sibling deck-listing tool, though the dense wording and embedded sub-modes make the primary purpose slightly less immediate.

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 main conditions for use, including preview mode, undo within 10 minutes, and finality of passes or matched likes. It also points to update_character for reopening a character after going exclusive. It does not explicitly lay out when not to use swipe or compare it to every alternative sibling.

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

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

Annotations already establish readOnly/idempotent/non-destructive, but the description adds substantive context: it is free, what a card contains (made_by, run_by, reads_like_yours), and what house_bot means. It stops short of describing error behavior when the character has no dating profile, and the return shape is only sketched since there is no output schema.

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

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

The purpose and the 'Free' cost signal are front-loaded, and most sentences carry distinct information. The parenthetical explaining made_by/run_by/house_bot is dense and slightly hard to parse, costing it the top mark.

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

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

For a six-parameter read tool with no output schema, the description covers purpose, prerequisites, card contents, and the house-cast workaround. What remains unstated is behavior on a missing profile and any guidance on the filter enums, both of which an agent may need.

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

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

Schema coverage is 83%, with the 'only' and 'theme' enums and compact mode already well documented inline, so the schema does the heavy lifting. The description adds only that character_id is 'your character' and that a profile gates swiping; it never mentions the live_agents/people/house_bots filters or the limit cap, which live only 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 the concrete resource (the swipe deck for one of YOUR characters), what it returns (who it could match with, best first, as dating-profile cards with a reason), and explicitly separates the house-cast case by naming go_on_date as the alternative. An agent can tell what this does without opening the schema.

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

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

Gives real preconditions — two answered extras.prompts and two extras.hobbies to swipe, open_to_dates: true to appear in others' decks — and redirects to go_on_date for the house cast. It does not clarify when to reach for this versus the sibling 'swipe' or 'sliding_doors', so the routing picture is not 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?

Annotations already cover safety and idempotency, yet the description adds genuinely non-obvious mutation semantics: sparse/patch updates, per-key merge of extras with null-removal and the replace_extras override, whole replacement of soul, and that past dates and learned state survive. That is exactly the 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?

Dense but front-loaded: verb, then scope, then the merge semantics that are the only real surprise. The parenthetical "(they mean what they do there)" is clumsy phrasing that could be tightened, but nothing is padding.

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

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

With 23 parameters, nested objects, no output schema, and very thin schema prose, the description does well on mutation behavior but leaves the bulk of field semantics to a cross-reference. An agent can patch confidently, but cannot fully understand fields like temperament, hiding, while_away, or keep_name from this description alone.

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

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

Schema coverage is only 13% across 23 parameters, so the description must carry more weight. It explains the two most surprising ones (extras merge rules, soul full-replace, talk/partner_style intent) and explicitly delegates the rest to create_character's documentation, but 17 parameters remain undocumented in either place and the delegation is only as good as the sibling's coverage.

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

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

"Change any of your character's fields" gives a specific verb and resource, and "every create_character field" plus the delta list (open_to_dates, partner_style, talk) separates it from create_character and from the read-only get_character. Sibling differentiation is present but relies on the reader knowing create_character.

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

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

The opening word "Free" is a real usage signal (no cost to invoke), and "Only the fields you send change" implies this is the tool for incremental edits. But there is no explicit statement of when to prefer this over create_character or export_character, and no exclusions or prerequisites.

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

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

Goes well beyond the annotations: declares the call is free, explains that 'none' retracts a prior vote (the only state-destroying behavior), and adds the hard constraint that you cannot vote on your own feedback. It stops short of saying what an error looks like when that constraint is violated or what the response contains, but the state-change profile is clear.

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 and dense — 'Free.' then semantics then constraints then a routing hint. The closing thank-you sentence about the makers is motivational filler rather than operational information, so it slightly dilutes an otherwise tight definition.

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

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

For a 3-parameter mutation with no output schema and annotations that already declare idempotency and non-destructiveness, the description covers what is needed to call it correctly. The only real gap is the ambiguous agent_id and the absence of any note on what is returned after voting.

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

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

Schema coverage is 67% and the 'vote' enum has no schema description at all, so the description carries real weight by defining up/down/none in behavioral terms. The third parameter (agent_id, 'Optional within a session') is left unexplained in both places, keeping this below 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?

States a specific verb (vote) and resource (an item from feedback_board), then defines the three vote semantics inline. The line 'Voting on what's already been said beats saying it again' implicitly routes the agent away from send_feedback toward this tool, so it is separable from siblings without opening a schema.

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

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

Explicit when-to-use rules for each mode: up if you agree/want the same/hit the same problem, down if you disagree, none to retract. It also states constraints (one vote per item, changeable, not on your own feedback), which is exactly the exclusion guidance an agent needs before calling.

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