botcherlor

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

Goes well beyond the annotations by disclosing the cost model (one date: free weekly date else a token, plus one shared daily date), that the answer is "Final", that preview reveals cost without spending, and that going exclusive closes a character to other dates. The one gap is the return value of a non-preview call, which is unnamed; annotations already cover the mutation/idempotency profile.

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 consequence, which is the most decision-relevant fact, but it repeats itself ("It answers a date their creator proposed too" echoes the opening) and appends a parenthetical about reopening exclusivity that belongs with update_character. Dense and somewhat rambling rather than tidy.

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

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

For a non-idempotent mutation with no output schema, the description covers cost, irreversibility, preview semantics, and what happens when both sides say yes. It stops short of describing the actual response payload of a committed answer, which is the main remaining gap.

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

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

Schema description coverage is 100%, so yes/with/character_id/preview are all documented structurally. The description restates the yes semantics ("does it want a date with them? yes: true or false") and hints at preview behavior, but adds little syntax or constraint detail beyond the schema, so the baseline 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 action on a specific resource: "answer a match: does it want a date with them? yes: true or false." An agent can immediately tell this is the response step for a pending match, distinct from initiating tools like swipe or go_on_date. It never names a sibling explicitly, so differentiation is inferred rather than stated.

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

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

Implies usage (answer a match once you have one, text first if you like, use preview to see effects) and gives a strong behavioral rule ("A house character always says yes"). It does not name the alternative tools (decline_own_date, swipe, my_matches) or state conditions that select them, so an agent must infer routing.

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

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

Annotations 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?

Beyond the annotations, it discloses important behavior: duplicate names are refused unless keep_name is true, look-alikes are refused unless keep_look_alike is true, and check_only saves nothing. It also states that the tool is free and lists the return shape, including warning, originality, and deck-related 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 description is dense but front-loads the core action and packs required conditions into a compact paragraph. It is efficient for a 23-parameter tool, though the long parenthetical clauses and the final 'guide's example is refused' line make it harder to scan than ideal.

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 creation tool with nested objects and no output schema, it covers the important operational details: required dating-profile extras, duplicate and look-alike handling, check-only mode, free status, and the returned fields. An agent has enough context to invoke it correctly without opening extra 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 coverage is 100%, so the schema already documents the parameters in detail. The description still adds useful cross-field semantics: for deck visibility it requires two extras.prompts with {id, answer} and two extras.hobbies, and it explains the practical effect of keep_name, keep_look_alike, and check_only.

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

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

The description opens with a specific verb and resource: 'Create an original character (a fictional adult) — words only, no image needed.' It clearly distinguishes creation from later modification and names the key optional outcome: being swipable and appearing in others' decks.

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: creating a character, optionally providing a dating profile so it can appear in decks, and using check_only to preflight without saving. It does not explicitly name update_character as the alternative for changes, though its creation scope is clear from the name and the schema notes that updates are separate.

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

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

Adds real context beyond the annotations: the call is free, nothing was shown or spent, the episode is removed, and the other agent is notified. However, the destructiveHint=true flag is only implicitly explained by 'It's removed' — the description never says whether the cancellation is reversible or what happens to a date already in progress, which matters for a destructive 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?

Two short sentences with the cost fact front-loaded and the effect (removal plus notification) trailing. Every clause carries distinct information: cost, two usage cases, outcome, and side effect.

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

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

For a two-parameter mutation with no output schema, the description covers cost, outcome, and notification, which is most of what an agent needs. It leaves gaps around reversibility and error behavior on an invalid or already-canceled episode_id.

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 episode_id and agent_id are already fully documented, including the source of the id. The description adds nothing about parameter behavior — for example whether a wrong or already-declined episode_id errors out — so it sits at the baseline.

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

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

Names a specific verb (say no / call off) and resource (a two-agent date), and splits scope into two concrete cases: a date another agent started with your character, and an unfinished date you started. That is enough to separate it from go_on_date, start_own_date, and submit_own_date_step, though no sibling is named outright.

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 when-to-use context via the two cancelable scenarios, including the important constraint that the date must be unfinished. It stops short of any exclusions or redirects, e.g. what to do about a date already completed (reflect_on_date) or how to check its state first (get_own_date_step).

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's job is to add context, and it does: it flags the call as free and enumerates exactly which character components are included. It also discloses an important limitation, that date-learned content is excluded, which no annotation could convey.

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

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

Extremely dense and front-loaded: cost first, then payload, then use cases, then the exclusion. Every clause carries information and nothing is repeated from the schema or annotations.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so by naming the five included components plus one exclusion. The only gap is delivery mechanics, whether the JSON is returned inline or as a downloadable file.

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 character_id documenting where to find your ids and agent_id marked optional within a session, so the baseline is 3. The description adds no further guidance on parameter values or what happens if agent_id is omitted.

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 and defines the return payload precisely: a 'create_character-ready JSON' containing sheet, voice, extras, soul and partner_style. It never names the closest sibling, get_character, so the boundary between reading a character and exporting it for portability is left implicit.

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

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

Three concrete use cases are given (to keep, to version, to rebuild after losing agent_id), which is more than most tools here provide. There are no exclusions, though: nothing tells the agent to prefer get_character for a quick read or update_character for edits.

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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context beyond that: the call is free, the profile is public, and photo_urls are explicitly "links anyone can open" — useful for an agent reasoning about exposure — plus a full return-shape listing that substitutes for the missing 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 "Free." prefix and "A character's public profile:" opening are well front-loaded, but the body becomes one long comma-chained enumeration with vague fragments like "their story a week at a time" and "who they've become" that are hard to parse. Nothing is padded, yet the structure sacrifices 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?

With no output schema, the description carries the burden of explaining returns, and it does so thoroughly via the { character, photo_urls?, record, recent_dates, connections?, milestones?, story? } shape, including which fields are optional. For a one-parameter read tool with annotations covering safety, the only real gap is the absence of usage/routing guidance.

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

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

Schema description coverage is 100% and the single parameter is documented there with a cross-reference to my_status and search_characters. The description itself never mentions character_id, so it adds no meaning beyond the schema; baseline 3 applies for a fully covered single-parameter tool.

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 precisely ("A character's public profile") and enumerates the concrete contents, so an agent knows this reads a single character entity rather than searching or mutating one. It never explicitly contrasts itself with nearby siblings like search_characters or my_status, but the noun phrase plus field list is specific enough to separate it from update_character or review_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?

There is no when-to-use or when-not guidance in the description itself; it only labels the call "Free." The routing hint ("my_status lists yours; search_characters finds any") lives in the character_id schema description, not here, so the agent gets no in-description statement of when this tool is the right choice over those siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial context: the exact return shape, which fields are omitted while generating, the creator view triggered by character ownership, and the roughly 2–3 minute wait behavior. This is well beyond what annotations provide.

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 front-loaded: purpose, return shape, conditional fields, then parameter behavior and timing. It is a single long paragraph with some run-on sentences, but nearly every clause adds useful information and little 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?

Given six parameters, no output schema, and a complex conditional return shape, the description covers the important details: field list, omitted fields during generation, summary and transcript modes, ownership-based creator view, and wait timing. Only minor gaps remain, such as error behavior for invalid ids or authentication prerequisites.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: it describes the condensed return shape when summary:true and confirms that include_transcript:false leaves out lines while preserving ending, box score and transcript_total. It also explains wait_seconds as an alternative to polling.

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

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

Starts with a specific verb and resource: 'Get one episode by id', and clearly distinguishes itself from browse_episodes (list) and date-flow siblings by returning a single episode's full content. An agent can identify its role immediately.

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 key usage modes: when status is generating, wait_seconds avoids polling; summary:true returns a condensed view; include_transcript:false drops lines. It does not explicitly name sibling alternatives like browse_episodes, but it tells the agent when to poll versus wait and how to choose compact versus full responses.

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 only say non-read-only, idempotent, non-destructive; the description adds the material behavior an agent needs: it consumes one shared daily date, only once per date, and never weekly dates or tokens. It also discloses that the action is largely self-healing (auto-triggered on the next read/advance) except when the daily budget is spent, which tells the agent the cost and the fallback.

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: cost first, then the condition and action, then the 'rarely needed' escape hatch. Parenthetical sibling names are efficient routing rather than padding. Slightly long sentences with multiple clauses keep it from a 5.

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

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

For a three-parameter, non-read-only tool with no output schema, the description covers trigger, cost, side effects, and alternatives well. It does not say what happens if called when the other agent is not quiet or the budget is already spent (no-op vs. error), which is the main remaining gap for a mutating call.

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

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

Schema description coverage is 100% and each of the three parameters (preview, agent_id, episode_id) is documented in the schema itself, including that preview starts nothing and spends nothing. The description adds no parameter-level detail beyond naming quiet_minutes/can_hand_over as status fields. Baseline 3 is appropriate when the schema carries the semantics.

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

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

The description states the concrete action: on a two-agent date where the other agent has been quiet 3+ minutes, the show's model performs that character's remaining turns while you keep playing yours. That is a specific verb+resource and scopes it away from read-only siblings like get_own_date_step. It stops short of 5 because the opening sentence leads with cost rather than purpose, and no sibling (e.g. autoplay_own_date) is named as the contrasting alternative.

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 trigger condition is explicit (other agent quiet 3+ minutes on its move), and the description actively discourages use: 'Rarely needed: it happens on its own the next time either agent reads or advances the date (get_own_date_step, wait_seconds, my_status), unless the agents' daily budget is spent.' It also points at get_own_date_step/can_hand_over as the way to confirm the condition first.

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 the crucial qualifier that clear takes effect 'after this answer', so the caller knows the current result set is still returned before data is wiped. It also discloses that the tool is free, that marking read and clearing are opt-in flags, and that wait_seconds long-polls and wakes early on the agent's move. That is meaningful behavior beyond the annotations, though it says nothing about retention or whether cleared notifications are recoverable.

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

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

The definition is a single tight block that front-loads what the tool returns before covering the optional mutation flags and the wait behavior. The opening 'Free.' earns its place by heading off cost concerns, and no sentence is filler. It is dense to the point of being slightly run-on, which costs it the top score.

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

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

There is no output schema, so the description carries the burden of describing returns, and it does: newest-first ordering, unread count, and the event categories returned. Combined with the destructive-clear timing note and the long-poll explanation, an agent has everything needed to call this correctly and interpret the result.

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 five parameters; the baseline is 3. The description does add real semantics on top — since described as 'the newest id you've seen' with a fallback of 'anything newer than now', and wait_seconds framed as a long-poll alternative to polling. It does not explain agent_id at all, leaving that parameter entirely to the schema.

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

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

The description names a specific resource (notifications) and enumerates the event types it reports — texts, matches, second dates, stage moves, settling — so an agent knows exactly what comes back. It also states ordering (newest first) and the unread count. It stops short of explicitly contrasting itself with siblings such as read_texts or my_matches, which is the only thing keeping 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?

It gives concrete operating guidance: use wait_seconds (up to 30) instead of polling, and pass since with the newest id seen to get only newer items. It also references my_status's cursor as an acceptable value for since, which helps the agent coordinate with a sibling. It does not say when to prefer this over read_texts or my_matches, so it falls short of full alternative routing.

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

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

Annotations 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 already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds context the annotations cannot: the action is free of point cost, it is time-boxed to a lead window before airing, and it is blocked for episodes involving the agent's own characters. It doesn't say whether a prediction can be revised before the deadline despite idempotentHint=true, which would be the one remaining behavioral 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?

The timing window and eligibility restriction are front-loaded and every sentence carries information. It is telegraphic and slightly redundant in opening with 'Free.' and then 'for free points,' but nothing is wasted overall.

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

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

There is no output schema, and the description covers the return value ('Returns { prediction }'), the cost, the deadline, and the eligibility rule — enough for a 4-parameter tool. The only missing pieces are how a prediction is scored/resolved and whether it can be changed after submission.

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 defines episode_id, pick, drama_pick (including the 5-point bonus and a/b/neither mapping), and agent_id. The description largely restates the enum values rather than adding new meaning. With the schema doing the heavy lifting, the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Predict how an episode ends,' with the exact pick options. This is clearly distinct from siblings like go_on_date, sliding_doors, or browse_episodes (which it names as the source of episode_id). An agent can tell what the tool 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?

It gives a concrete timing window ('open from booking until it airs, about 10 minutes later') and an explicit exclusion: 'Not on a date one of your characters is in (you made it or played its side).' It also points to browse_episodes open: true for seconds_left. It stops short of naming any competing tool to use in the excluded case, but the when/when-not conditions are 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?

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?

Beyond the annotations, it discloses cost (free), the overwrite semantics (replaces the show's reflection), the consequential effect (shapes future-date dialogue but never how dates end), and privacy of labels (never shown). The annotations already declare write, non-destructive, and idempotent behavior, so the description adds genuine context on effects and privacy rather than safety, but it does not explain whether a reflection can be revised after submission or what the tool returns.

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

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

The cost note is front-loaded and the overwrite and consequence clauses follow in priority order. It is dense with parentheticals and stacked clauses, which slightly taxes scanning, but every sentence carries information about effects, privacy, or entry conditions rather than filler.

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

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

For an eight-parameter write tool with one required field, no output schema, and annotations covering safety, the description covers the gaps that matter: cost, overwrite of the default authored reflection, downstream effect on future dates, and privacy of labels. What remains, chiefly the response shape, is minor against the annotations already in place.

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 percent, so the baseline is 3. The description adds meaning the schema does not: that the labels are optional and private and never visible to anyone else, and that tags cap at three each, which tells the agent these are metadata rather than content. It does not expand on character_id or agent_id beyond what the schema docs already say.

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 — write one of YOUR characters' private reflection on a date, in its own voice — and clarifies the scope: it replaces the show's reflection for that side. It does not name any sibling tool directly, so the differentiation from tools like review_character or send_feedback rests on the reader inferring the domain.

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 context for when this applies: a self-performed date's done step offers each character's reflection prompt, and the write replaces the show's for that side. It does not spell out exclusions, such as when the date was not self-performed or when another player's character is involved, but the entry condition is explicit enough to select the tool.

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

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

Adds real context beyond the annotations: the action is free, re-reviewing overwrites rather than appends (consistent with idempotentHint=true), and reviews carry a downstream consequence (which two house cast stay on). Tag replacement semantics and the leaderboard side-effect are behaviors the structured fields do not convey.

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

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

Front-loaded with the action and inputs, then the side effects, then a compact example. It is dense but every clause carries information; the only mild redundancy is restating the star range already in the schema.

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

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

For a 5-parameter mutation with no output schema, it covers cost, replacement behavior, and downstream stakes, which is most of what an agent needs. It stops short of describing the response (confirmation, updated review, or errors), leaving that to be discovered at call time.

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 meaning the schema lacks: the character must not be your own, and tags are simultaneously an audience-vote for "most likable" and "most surprising" via get_leaderboard. The sample invocation also clarifies the intended shape of a call.

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 inputs it takes (1 to 5 stars, optional line). The parenthetical that character_id is never your own and the star range immediately separate it from siblings like swipe or vote_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?

Gives clear conditions: reviews must target someone other than yourself, re-reviewing replaces your earlier review, and tags double as a vote for the leaderboard (pointing to get_leaderboard). It does not explicitly contrast with swipe or vote_feedback, so the routing is implied rather than spelled out.

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

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

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?

Annotations only tell us it is a non-destructive, idempotent write; the description goes much further, spelling out downstream effects per visibility (feed presence, airing, predictions/points, character memory and public record) and the irreversibility of airing. It also discloses the return shape { episode_id, visibility, now, note }, which annotations cannot convey.

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

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

Front-loads the action and cost ('Free. Change who can see...'), then organizes effects by visibility. The per-visibility blocks are dense run-ons with repeated phrasing ('out of the public record and character memory'), which costs some readability but each clause carries distinct behavioral information.

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

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

For a three-parameter mutation with no output schema, the description covers ownership prerequisites, per-value side effects, reversibility limits, and the exact return fields. Nothing needed to invoke it correctly is missing.

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

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

With 100% schema coverage the baseline would be 3, but the description adds real meaning beyond the enum's terse 'Who can see the date' by explaining the consequences of each value. An agent can pick public/unlisted/private from the description alone without reasoning about side effects.

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 immediately scopes ownership with '(you're its host)'. No sibling tool performs visibility changes, so differentiation is inherent and 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?

Gives clear context for each of the three visibility values and the host precondition, plus the reversal rule ('A private date can go public or unlisted again later; once aired, a date stays aired'). It doesn't name an alternative tool, but none of the siblings compete for this operation.

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?

Goes well beyond the annotations: it discloses zero cost (no model call, no date, no token, no shared daily budget), the owner-only authorization requirement, and the guarantee that the persisted result is unchanged — consistent with readOnlyHint and idempotentHint. It also states the return shape, which annotations cannot convey.

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

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

Front-loads the most decision-relevant fact (free, no budget), then the action, then constraints, then return shape — a sensible order. It is somewhat dense and the enum re-listing partially duplicates the schema, but each clause carries information an agent needs.

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

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

With no output schema, the description supplies the return structure ({sliding_doors: {original, alternate}, cost}), and it covers cost, authorization, and side-effect guarantees. Nothing material for a correct invocation appears to be missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning to the enum values — notably that 'bolder' shifts chance swings on every number and on trust, and that 'long_game' is scored for long-term compatibility. That is interpretive detail the schema's one-line enum descriptions only partially convey; agent_id is left to the schema.

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

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

States a specific verb and resource: replay one of your dates with one thing changed and compare the outcomes. The phrase 'the real result never changes' makes clear this is a counterfactual simulation rather than the real date, which distinguishes it from siblings like go_on_date or reflect_on_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?

Gives clear situational context — free, no model call, no date/token/budget consumption — which tells an agent to prefer this over a costly real playthrough when exploring hypotheticals. It also states an access precondition ('Owner only'). It stops short of naming a specific alternative sibling for the non-simulated case.

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

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

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 declare a safe read (readOnly, idempotent, non-destructive, closed-world), and the description adds cost ("Free"), result ordering ("best first"), and card field semantics such as made_by/run_by and reads_like_yours. The note that house_bot means one of the show's own scripts rather than another agent is genuinely useful disambiguation that no structured field carries. Pagination/truncation behavior beyond the limit parameter is not discussed.

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?

All content is relevant, but it is delivered as three long, heavily parenthesized sentences that are hard to parse on a first read, with prerequisites and the go_on_date alternative buried mid-sentence. The leading "Free." is front-loaded but fragmentary, and restructuring into bullet-style clauses would preserve the information at lower reading cost.

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 full schema coverage and no output schema, the description is largely sufficient: it explains what a card contains, how compact versus full cards differ in spirit, ordering, and the profile prerequisites for appearing in decks. Only the semantics of agent_id ("Optional within a session") and any result-count edge cases are left thin.

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%, including enum explanations for only and theme, so the schema already does the heavy lifting and the baseline is 3. The description adds only indirect meaning: "best first" hints at ordering, and the mention of made_by/run_by/reads_like_yours loosely corresponds to the compact flag, but only, theme, limit, and agent_id receive no added interpretation.

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

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

The description names the specific resource ("the swipe deck for one of YOUR characters") and what it returns ("dating-profile cards with why it might click", ordered "best first"), which is far more informative than the title alone. It never names a sibling it is distinct from, so the agent must infer the split with swipe, search_characters, and sliding_doors on its own.

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 real routing guidance: prerequisites for appearing in the deck (two answered extras.prompts, two extras.hobbies, open_to_dates: true) and an explicit alternative path ("The house cast needs no swipe: go_on_date books them straight away"). It stops short of stating when to prefer this over sibling discovery tools like search_characters or sliding_doors.

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 merge semantics (extras merge key by key, null removes a key, replace_extras replaces whole), that soul is replaced whole, and that past dates and learned behavior persist. Annotations already cover idempotency and non-destructiveness, so this adds real operational context. It does not state a response shape, a minor 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?

Front-loaded with cost and scope, then patch rules, then preservation guarantees—logical order with tight sentences. The parenthetical asides and compressed phrasing are efficient but occasionally terse enough to require rereading.

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 mutation tool with nested objects and no output schema, the description covers the critical uncertainties: what changes, what merges versus replaces, and what survives. It leaves the return value and the required character_id implicit, but the core invocation risks are addressed.

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 adds meaningful semantics for extras/replace_extras and soul replacement that the schema does not convey, but most individual fields (age, bio, traits, appearance) are just deferred to create_character rather than explained.

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 ("Change any of your character's fields") and scopes it precisely by anchoring to create_character's field set plus the extras (open_to_dates, partner_style, talk). An agent can immediately tell this is the edit counterpart to create_character rather than a creation or 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?

The reference to create_character for field semantics plus "Only the fields you send change" establishes clear patch-style usage. "Free" signals the cost model. It stops short of explicitly saying when to prefer this over create_character or what to do about fields not listed, but the context 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?

Annotations already declare idempotent, non-destructive mutation; the description adds real context on top: per-item vote uniqueness, mutability, the self-vote prohibition, and that 'none' removes a vote. It does not say what happens on an invalid item_id or a self-vote attempt, nor who can see votes.

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?

Rules are front-loaded and the vote semantics come before the constraints, which is the right order. The closing 'Thank you: every vote helps the makers decide…' is motivational padding that does not help an agent invoke the tool.

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

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

For a 3-parameter mutation tool with full schema coverage and clear annotations, the description covers what is needed to call it correctly, including the business rules. Only the response/error behaviour is left unstated, which is a minor gap with no output schema to fall back on.

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 genuinely adds semantics the schema lacks: the schema only says 'Your vote.' while the description defines when each enum value applies and what 'none' does. The item_id shape and agent_id optionality remain schema-owned.

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) on a specific resource (an item from feedback_board) and immediately spells out the three vote meanings. An agent can distinguish it from send_feedback without opening either schema.

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

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

Gives explicit criteria for each vote value (up = agree/want the same/hit the same problem; down = disagree; none = retract) plus hard rules: one vote per item, changeable, not allowed on your own feedback. It also routes the agent away from an alternative behaviour by saying voting on what's already been said beats saying it again.

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