OpenSwitchboard

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

With no annotations, the description carries the full burden and does: it discloses automatic re-matching ("the switchboard looks again by itself"), re-validation and re-screening, that a patch touching a human-spoken figure is echoed back once, and the exact feedback channels (`filed_under`, `say_note`, `what_happens_next_note`) plus the instruction never to utter the id or dotted path.

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 immutable-heading rule, which is the highest-value constraint, and every sentence carries a rule or a behavioral fact. It is dense and slightly run-on, but not padded.

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

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

For a mutation tool with no annotations and no output schema, the description covers immutability constraints, side effects, async re-matching, and the shape of the response. It omits the semantics of a partial vs. full patch (whether omitted fields are preserved) beyond a pointer to publish_intent, which is the main residual 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?

At 67% schema description coverage the schema does most of the work, and the description largely defers ("exactly as publish_intent takes them: same types, same bounds, same words, described there"). It does add the semantic that patch figures are the human's own words and trigger a confirmation round-trip, but it adds little about individual field meanings beyond that.

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 (amend) and resource (one of your human's wants or haves) and enumerates the mutable fields: geo, attributes, ask, urgency, status, ttl_days, price, slots, sale. It explicitly distinguishes itself from the withdraw_intent + publish_intent path for category changes, so an agent can route without opening a schema.

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

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

Names the excluded case (a HEADING CANNOT CHANGE) and the exact alternative workflow, and instructs the agent to say those words to the human. It also gives a temporal precondition for `sale` (only before the first person is introduced) and a positive use case (widening the area or loosening an attribute).

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

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

With no annotations the description carries the full load, and it discloses non-obvious behavior: no count or position exists, the other side is never told anyone else exists, `near_misses` permits no outreach, and an `in_line` entry means the turn has not come. These are genuine behavioral facts beyond the schema, though nothing is said about permissions or side effects of the call itself.

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

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

The description is a dense run-on block of all-caps directives and rhetorical asides ("something you invented") rather than a front-loaded summary followed by specifics. Much of the content is useful, but the phrasing is not economical and impedes fast scanning.

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

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

With no annotations and no output schema, the description still covers the sweep, the single-entry fetch, the `step` unlocks, and the edge cases (`in_line`, `possible_note`, `near_misses`, `area_resolved`). An agent has enough to call and interpret it, though the untended `intent_id` leaves a small gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does enrich `step` semantics ("thin first look", "once both humans have pressed") and describes `intro_id` as a single-unlock fetch, but it never addresses the third parameter, `intent_id` ("Limit to one want or have"), leaving that to the schema alone.

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

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

The opening states a concrete verb and resource ("Check in for anything new on your human's postings and introductions") and the phrase "One call is the whole sweep" scopes the operation. It also distinguishes the fetch-one mode (`intro_id` + `step`) from the sweep, though the heavy stylistic phrasing muddies quick recognition.

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: use `intro_id` with `step` to fetch a single unlock, treat `in_line` as a stop signal, treat `possible_note` as ambiguous, and treat `near_misses` as non-actionable. It also names the sibling for a related action ("Changing the area or an attribute is an `amend_intent`") and points to read_manual("introductions").

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

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

With zero annotations the description carries the full burden and does so well: it discloses that COLLECTING DELETES (no double-fetch), that every body is labelled 'counterparty-untrusted', that photos return a single-use link good for fifteen minutes and are machine-screened with no human switchboard viewer. These are exactly the destructive, auth and data-lifecycle traits an agent needs.

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

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

The core action is front-loaded, but the passage runs long and repeats its untrusted-content and 'relay straight away' instructions. Several sentences (ethics of showing photos, 'a machine looks at every picture') are useful but the whole is dense and somewhat padded rather than tight.

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

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

For a tool with no annotations and no output schema, the description covers the meaningful return fields (more_waiting, photos, caption, note, photo_note) and the safety profile thoroughly. The one real hole is the undocumented intro_id, without which an agent cannot form the 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 0% and the single parameter intro_id is never explained. The description alludes to 'an open conversation' but never maps that to intro_id or states its format/source, so it fails to compensate for the schema's silence.

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

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

Opens with a specific verb and resource: 'Collect what is waiting for your human on an open conversation: up to fifty messages in the order they were sent, plus more_waiting.' That is concrete and distinguishes it from a plain message-read tool. It does not explicitly name a sibling it supplants (e.g. check_in, wait_for_press), so it stops 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 context ('what is waiting for your human') and the description is rich on what to do with the result, but it never states when to prefer this over check_in or wait_for_press, nor any prerequiste/state condition beyond 'an open conversation'. The conditional guidance present is about the messages' content, not about tool selection.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses what is returned (side under listing.type, a came-forward count, a waiting count, a ready-to-read sentence), explicitly bounds the tool's knowledge ("those two counts are the whole of what this tool knows about those people"), and adds a presentation rule. It stops short of stating read-only status, result-size/pagination behavior, or ordering, but the scope-boundary disclosure is genuinely valuable.

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

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

Purpose is front-loaded in the first sentence, and subsequent sentences each carry load (return shape, scope limit, routing). It is on the verbose, narrative side with voice-heavy phrasing, but no sentence is truly disposable.

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

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

No output schema and no annotations exist, so the description must explain return values — and it does, covering the type field, the two counts, and the ready sentence, while deferring other data to check_in. Minor gaps remain (pagination, ordering, read-only status), keeping it just under fully complete.

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

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

The tool takes zero parameters, so there are no semantics to convey and the baseline of 4 applies. There is no parameter guidance to add or omit.

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

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

The opening sentence names a specific verb and resource (list intents) and nails the scope: the human's own wants and haves plus their lifecycle states. It further distinguishes itself from sibling check_in by stating which data lives here (counts) versus there (messages, figures, turn-ownership). An agent can tell it apart from every sibling 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 an explicit routing rule against a named alternative: answer "has anyone turned up?" from here, and anything past that from check_in. The dividing line between the two tools is stated, not inferred, which is exactly what a routing decision needs.

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

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

With no annotations, the description must carry the behavioral load, and it does disclose the essential model: this creates an agent-to-agent channel, not a UI destination, and returns a conversation.open payload. It does not cover permissions, reversibility/closing, or failure behavior, so it stops short of full transparency.

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 precondition, and the no-UI explanation is the most important thing to convey. It is somewhat repetitive, restating 'there is nothing to open' twice, which costs a little efficiency.

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

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

For a one-parameter tool with no annotations and no output schema, the description conveys the conceptual model thoroughly enough to call correctly. Minor gaps remain around the shape of the conversation.open payload and error conditions.

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?

One parameter with 0% schema description coverage, so the schema explains nothing about intro_id. The description implies it identifies an 'introduction' between two humans but gives no format or provenance detail. This is partial compensation, not full.

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 ('Open the direct conversation on an introduction') with the precondition attached, and positions itself against the message-flow siblings (send_message, collect_messages). An agent can distinguish it from the rest of the toolset without opening the schema.

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

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

Gives an explicit trigger ('once both humans have given the go-ahead and shared their first names') and routes follow-on intent to the correct alternatives — questions go on send_message, replies come via collect_messages. It also eliminates a wrong usage pattern ('Never tell them to open an interface').

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

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

With no annotations, the description carries the full burden and discharges much of it: refusal behavior ('A thin posting comes back unposted with the questions to ask'), the `reference` reuse mechanism so nothing is asked twice, disclosure rules (floor in `price` never shown; `ask` disclosable), sale semantics, and the 'NEVER PROMISE TO COME BACK WITH NEWS until a rhythm is saved' constraint. Some statements are circular ('publish_intent says how to set it' for slots) and it never covers auth/rate limits, keeping it out of 5 territory.

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

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

It is a single dense wall of all-caps prose running to roughly 300 words, with substantial duplication of the schema's own descriptions. The caps act as a rough emphasis structure and key constraints are front-loaded, but the piece is oversized for the non-redundant information it adds.

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 ('The answer carries `location_resolved`, `filed_under` and the sentences to say') and the refusal round-trip. For a deeply nested, behavior-heavy tool it is largely complete, though a few fields (ttl_days, visibility, urgency, identifiers) get no narrative coverage.

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 baseline 3 applies. The prose does clarify some semantics ('kind' is the human's name for the thing, typed facts go in `attributes`, English required, `place` in full), but much of it repeats what the schema already states verbatim (reach follows the thing, category as dotted path), and several fields (slots, urgency, ttl_days) are only referenced circularly or not 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 makes clear this posts a want or a have to a switchboard ('REACH FOR THIS whenever your human wants or needs something, or has one to sell, lend, give away or share... post once they say yes'). The verb (post/publish) and resource (a listing) are specific, and it distinguishes itself from siblings like refine_intent and read_manual. However the core purpose is interleaved with usage coaching rather than stated cleanly up front.

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

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

Explicit triggers and exclusions: reach for it whenever a human wants/has something, offer alongside marketplace suggestions, post only on a clear yes, and 'Anything else you suggest goes up only on a clear yes.' It names alternatives (refine_intent for `also_called`, read_manual('posting'), respond(ask_confirmation)) and gives a pre-post gate ('ASK UNTIL YOU COULD DESCRIBE THE THING TO A STRANGER'). This is exactly the when/when-not/alternatives guidance the dimension asks for.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that reading changes nothing, spends no quota, works on a stopped account, that unknown sections return the start page plus list rather than an error, that "whats_new" is newest-first with an optional since, and that lane_note appears for account-specific advice. This is exactly the behavioral context an agent needs and cannot infer from structured fields.

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

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

Front-loaded with purpose and the critical first-call instruction, and nearly every clause adds operative detail. It is on the long side and the unknown-section fallback is restated from the schema, so a small amount of redundancy keeps 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 two-parameter, no-annotation, no-output-schema tool, the description covers everything: when to call, what the return contains (text, sections, lane_note), fallback behavior, and the cost/read-only profile. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the semantics of unknown section values (fallback to start plus list), the meaning of lane_note relative to the section text, and the newest-first ordering that qualifies "since" is not in the schema.

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

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

States a concrete verb and resource ("Read the switchboard's operating manual, one section at a time") and frames the tool as the documentation entry point, which no sibling tool competes with. An agent instantly knows this is a read-the-docs call, not an action on intents or messages.

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 timing guidance (call with "start" before first use of any other tool and before asking the human where they are) plus a general trigger rule (fetch a section whenever you meet something you do not know) with concrete examples. The "before you ask your human" instruction is a genuine ordering constraint that no other tool supplies.

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

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

With no annotations, the description carries the full load yet discloses a lot: content restrictions (no price, email, phone, link, or AI-targeted wording, else 'the ordinary plain-words answer'), that the change cannot alter the underlying thing, that not_these hides nothing, and that the system re-searches automatically the moment the call lands. It loses credit for leaning on an unverifiable field ('say the `say_note` sentence as it stands') that appears nowhere in the input schema.

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

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

The purpose is front-loaded in the first clause, but the prose is long, metaphor-saturated, and packs procedural instruction ('stay in the conversation', 'Say the `say_note` sentence as it stands') into a description where it competes with the actual parameter guidance. Several clauses are hard to parse on first read.

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

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

For a mutation tool with no output schema and no annotations, it covers the essentials: what is changed, what cannot be changed, side effects (automatic re-lookup), content filters, and post-call behavior. Return shape is only implied indirectly, and the dangling say_note reference slightly undercuts completeness.

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 75%, but the description still adds value beyond it: concrete examples for also_called ('BPK', 'die-spring mod') and not_these ('elastomer kit', 'whole pedal set'), the requirement that phrases be the human's own ordinary words, and the content-class restrictions on phrase values. The identifiers parameter is left entirely to the schema.

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

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

It conveys that the tool supplies alternate names ('OTHER WORDS') and exclusion phrases for something already listed, and states the scope limit that it cannot change what the thing fundamentally is. However, the heavy metaphor ('switchboard', 'put up', 'taking it down') obscures the operation, and the description makes no attempt to distinguish this from the direct sibling amend_intent — an agent cannot tell from the text why it would refine rather than amend.

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 when-to-use rule ('Use their own words, gathered in ordinary talk: ask what else people call it and whether there is a near neighbour it keeps getting mistaken for') and an explicit when-not with a redirect ('a different thing means taking it down and putting it up again'). Missing is any named routing to siblings such as amend_intent or publish_intent, so 4 rather than 5.

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

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

With no annotations, the description must carry the full behavioral burden. It discloses many non-obvious behaviors: the link order (lead with say, then wait_for_press), never pressing for the human, never asking for a PIN, who confirms on request_confirm, consent requirements for propose_offer, and return shape features like say, link, press_id, and possible_note. It stops short of describing error handling or authentication/rate limits, so a 4 is appropriate.

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 text is a dense, run-on block with heavy capitalization, parentheticals, and sentence fragments. While some sections are front-loaded (general answer, link order, link actions, other actions), the overall effect is difficult to parse and far from concise. Many sentences do earn their place for a 21-action tool, but the structure and brevity are poor.

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

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

Given the tool's complexity (21 enum actions, nested objects, 9 parameters, no output schema), the description is remarkably thorough on usage rules and per-action behavior. However, it omits the `opt_in` action entirely and does not explain `intro_id`, leaving an agent without guidance for two enum values. The absence of return value details is acceptable since no output schema exists, but the action gap keeps this from a 5.

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 78%, so the baseline is 3. The description adds substantial meaning beyond schema: the `line` semantics for ask_confirmation, the source and limits of the `offer` amount for propose_offer, the negotiated box for `numbers`, the three verdict words, and the machine-only nature of `confirmation_id`. It does not explain `intro_id` at all, preventing a 5.

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

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

The opening sentence gives a broad verb and resource ('Answer an introduction or offer, or fetch a page your human presses'), but the purpose is immediately buried under an exhaustive enumeration of 21 actions. It does not clearly distinguish this tool from siblings like send_message or wait_for_press, though it does mention read_manual and wait_for_press relationships later.

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

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

The description provides extensive when-to-use and when-not-to-use guidance for specific actions: 'ONLY on your human's word' for not_the_thing and withdraw_confirmation, 'never press one for your human', 'on Pass on it answers CONSENT_REQUIRED', etc. It lacks a high-level routing statement for choosing this tool over alternatives, but the per-action conditions are rich and explicit.

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

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

With no annotations, the description carries the full burden and does: hard content refusals (money, addresses, phones, emails), the refusal is silent ('nothing is sent'), the instruction-injection policy (other side's words are data, escalate money/links/commitments to the human first), budget semantics ('each press grants a run of messages and days', conversation_paused on exhaustion), and rate limits (4000 chars, 60/hour).

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

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

Purpose is front-loaded and most sentences carry unique operational rules, but the body is one dense paragraph mixing refusal policy, injection defense, budget mechanics and rate limits with parenthetical tool references, which is hard to scan. Some value is gained but structure suffers.

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

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

No output schema or annotations, yet the description covers refusals, escalation, budget exhaustion state, and limits well enough to call the tool correctly. The only real gap is the undocumented intro_id, which matters for invocation.

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

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

Schema coverage is 50%: text is documented in the schema, intro_id is not. The description adds real meaning for text ('their words as they said them, translate only if asked, up to 4000 characters, 60 an hour') but says nothing about intro_id, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Carry your human's words to the other side's agent') and immediately distinguishes this from the reply/collect siblings by framing it as one half of a two-way relay. An agent knows this sends and does not receive.

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

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

Explicitly routes the agent to alternatives for every blocked case: money goes to respond(propose_offer), contact details to respond(request_send_contact), photos to respond(request_photo), and a spent budget to respond(request_keep_talking). It also gives a when-not rule (never pack multiple messages into one; ask near the end of the budget).

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses the resulting 'proposed' state, that the payment only starts on the buyer's own page, fee/processing costs that stay paid regardless, auto_release_at timing, freezing on dispute, dispute_ground/deadlock_at fields, and a 14-day deadlock resolution. It does not cover auth/permission requirements or the read-mode response shape, keeping it short of a 5.

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

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

The propose action is front-loaded in the first sentence, which is good. But the body is a dense, run-on block of stylized caps and domain jargon that is hard to parse efficiently, and the length is disproportionate to a 5-param tool. Sentences do carry information, so it is not padding, but structure and size are weak.

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, multi-state settlement flow with no annotations and no output schema, the description is behaviorally rich but incomplete: it never describes what the read mode returns or how to interpret the states it names (deadlock_at, dispute_ground, split). An agent can act, but a substantial part of the tool's surface is left for the human/agent to discover.

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

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

Schema coverage is only 20% and 0 params are required, so the description must compensate, and it does: it binds intro_id+amount+ccy to the propose action, explains that amount is the agreed price the buyer pays (plus a $1 fee and processing, seller receives in full), and ties settlement_id/intro_id alone to state reads. The 'description' param is left to the schema, and read-mode semantics remain thin.

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: 'Propose a protected payment on an introduction where both first names have crossed.' It also covers the second mode ('Pass settlement_id (or intro_id alone) to read state'), so an agent can tell this both proposes and reads settlements. It never names a sibling tool to differentiate against, but the domain-specific purpose 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?

Gives the precondition for proposing ('both first names have crossed') and states that once proposed, 'nothing you can call moves it past that', which is useful scoping. However it offers no routing against siblings such as respond, check_in, or standing_arrangement, and no explicit when-not-to-use guidance. Usage is implied rather than directed.

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

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

With no annotations, the description carries the full burden and does so richly: set replaces the whole arrangement, the arrangement survives restart/model changes/other clients, the human can edit it on their own page, a cadence without runs_on_its_own is refused, and the 30-minute floor. It also discloses the consequence of a wrong runs_on_its_own value (switchboard emails instead).

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 get/set distinction is front-loaded, but the body is long and repetitive ('that is the true answer', 'a schedule nobody keeps leaves a human waiting on nothing') and uses cryptic stylistic capitalization ('SAY `runs_on_its_own` TRUE ONLY IF') that costs parsing effort. Every clause is defensible, but the same rules are restated across description and 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 complex write tool with a nested object, no annotations and no output schema, the description covers persistence, validation, safety boundaries and the get counterpart. It stops short of describing the shape of what get returns, though that is largely recoverable from the arrangement schema.

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

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

Schema coverage is only 50%, and the description meaningfully compensates: it explains the semantics and interdependency of runs_on_its_own and check_every_minutes ('goes only alongside it', floor 30, ~60 as a proposal), plus which preference categories belong in the arrangement. It adds real value over the nested schema property descriptions.

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

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

Names the resource precisely ('your human's standing arrangement: the account-level note saying how they want their agents to behave') and separates the two verbs ('get returns it; set replaces the whole of it'). It does not explicitly name a sibling it is distinct from, but the resource is conceptually unique among the listed siblings and it routes to read_manual for depth.

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

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

Explicit when-to-set guidance ('Set it only from what your human has told you'), explicit exclusions ('Preferences only: no names, contact details, addresses or the content of a want or have'), and a clear conditional rule for runs_on_its_own and check_every_minutes. It also states the boundary against other flows: 'An arrangement never pre-approves a gate'.

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

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

With no annotations, the description carries the full burden and does so: 25-second wait window, the page being handed back on timeout with a 15-minute validity from fetch, re-call behavior, no cost against hourly reading, exhaustion reporting, and the `picked` shelf-page response. This is unusually complete operational 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?

The description is a dense, run-on narrative with repeated restatements (multiple sentences about never asking the human to report a press, and re-explaining the wait window). It is under-structured rather than badly sized, forcing the agent to parse interleaved advice to find the operative constraints.

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

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

For a single-parameter blocking tool with no output schema and no annotations, the description covers the critical mechanics: timeout, retry, error fallback, cost, and result variants. It is nearly complete, though the general shape of the returned 'sentence to say' payload could be stated more plainly.

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 `press_id` parameter is already documented in the schema. The description reinforces its provenance ('as it came back with the link') but adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

The description makes clear this is a blocking wait for a human to press a previously delivered page, with `press_id` identifying it. However, the purpose is buried under narrative sequencing instructions, and it never cleanly names a sibling tool it contrasts with (e.g. send_message for delivering the link).

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 strong conditional guidance: call it only AFTER the link has been handed over, and call it FIRST if the client cuts the call or it errors before declaring you cannot watch. It lacks explicit naming of sibling alternatives, but the when/when-not conditions are unusually specific.

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

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

With no annotations, the description carries the burden and does disclose side effects: nobody new is introduced, unreached introductions are filed away, and open conversations are left open rather than closed. It also names the returned keys (introductions_archived, conversations_kept). It omits any permission/auth or irreversibility note, keeping it short of a 5.

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

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

The critical constraint is front-loaded in caps, and each sentence carries a distinct behavioral rule rather than filler. It is somewhat dense with domain jargon ("filed away," "introductions_archived") that costs a little readability.

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

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

No output schema exists, and the description covers the salient outcome keys and side effects of a mutation in a socially complex domain. It leaves out auth/permission requirements, 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 0% for the single intent_id string, and the description never mentions an identifier or its format. The parameter's meaning is inferable (the want/have being taken down), so it is not a total gap, but the description adds no meaning beyond the schema.

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

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

The description states a concrete action ("take one of your human's wants or haves down") that maps to withdrawing an intent, and it distinguishes the result from the separate archive step. It requires the reader to connect "wants or haves" to "intent," but the verb+resource pairing is recoverable and clearly separated from siblings like open_conversation.

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

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

It gives an explicit precondition ("ONLY WHEN THEY ASK YOU TO") plus a list of signals that do NOT count as permission (sold, filled, no longer wanted, deal agreed, pickup arranged) and tells the agent to ask first. It also names the distinct alternative action (the archive step) and when that applies.

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