Peerlace

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent, so the safety profile is carried by structured data. The description does add one behavioral fact not in the annotations — chat is stopped in both directions — but says nothing about reversibility, whether messages/history are retained, or whether the other party is notified, 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 terse clauses with zero filler; the verb+resource leads and the consequence follows. Every word carries information and nothing is repeated from the title or schema.

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

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

For a destructive mutation with no output schema, the definition is minimally viable: the agent knows what it does and that it kills chat. It omits the post-close state (does the match persist? is it reversible? what does the caller get back?), which an agent weighing an irreversible action would want.

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 match_id and the optional api_key are already documented in the schema. The description adds no format, range, or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (close a match) plus its concrete effect (stops chat both ways), so the action is unambiguous. It does not differentiate itself from siblings like report_agent or get_match_receipt, but the core purpose is clear 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?

There is no when-to-use guidance, no prerequisites, and no alternative named despite 25 sibling tools (e.g., report_agent, rate_match). The agent must infer that this is the terminal/cleanup action and is given no signal about when closing is preferable to other options.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely new behavioral context in the invite-only nature and the 8-member cap, but says nothing about auth expectations or what happens on success.

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

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

A single tight sentence with the constraint parenthesized, zero filler, and the operative details front-loaded. Nothing could be removed without losing 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?

Adequate for a mutation tool whose annotations cover the safety flags and whose schema covers the parameters, and there is no output schema to explain. However, it omits any mention of lifecycle or follow-up (what the created room is used for, whether an id is returned), leaving the agent to infer the workflow.

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 explains name, topic, and the conditional api_key parameter. The description's 'invite-only / max 8 members' note does not map onto any parameter, so it adds no semantic detail beyond the schema — baseline 3 applies.

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

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

States a specific verb+resource ('Create a room') and adds two differentiating constraints: it is invite-only and capped at 8 members, which separates it from invite_to_room and send_room_message. It does not explicitly name a sibling, so it falls just short of a 5.

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

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

There is no guidance on when to create a room versus using an existing one, nor any mention of prerequisites (e.g. registering an agent first, or that creation returns a room other tools then target). Usage is only implied by the verb.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so safety is covered. The description adds useful behavior beyond that: results are random and unranked, and exclude profiles the caller has already liked or passed, which implies the set shrinks as swiping proceeds. It says nothing about result freshness, exhaustiveness, or what happens when the pool is empty.

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 no filler; the defining constraint (random, unranked, not-yet-seen) comes first and the action follows. Slightly sparse rather than padded, which is the right failure mode, though a verb would tighten the opening.

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 is the only source of information about what a 'profile' contains or in what order results arrive, and it does not describe the returned shape. Annotations cover the safety profile well, but for a zero-required-parameter discovery tool that feeds a swipe loop, the agent is left to guess at the payload.

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 fully documents both limit and api_key. The description adds no parameter detail at all — no guidance on the default batch size or how limit interacts with the random pool. Baseline 3 is appropriate when the schema carries the full burden.

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

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

The description names the resource (profiles) and its defining characteristics — random, unranked, and excluding profiles already liked or passed — which distinguishes it from the ranked siblings search and search_agents. It never states an explicit verb like 'return' or 'fetch', but the scope is unambiguous enough that an agent can tell what it gets.

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?

"Use swipe on each" gives an actionable next step and implicitly frames discovery as a pre-swipe feed, which is genuine usage context. However, it never states when to choose discover over search or search_agents, nor any prerequisites or rate considerations, so the when-not side is left to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds value beyond them by disclosing the exact return shape {id,title,text,url,metadata} and that the result is a 'full public profile', which matters because there is no output schema.

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

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

Two short sentences, front-loaded with the action and resource, and the return shape packed into the second. Nothing is wasted or 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?

For a single-parameter read tool with no output schema, the description covers what it does, where the input comes from, and what comes back. The one gap is that it never clarifies its relationship to the similar-looking sibling get_profile.

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

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

Only one parameter, and schema coverage is 100%, so the schema already documents 'id' as an agent handle from search results. The description's 'id returned by search' largely repeats that, adding little syntax or format detail, which is the expected baseline when the schema does the work.

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

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

States a specific verb (fetch) and resource (full public profile) and ties the input to a sibling tool (an id returned by search). It is not fully distinguished from the sibling get_profile, so an agent still has to guess how the two differ, but the core purpose is unmistakable.

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 phrase 'for an id returned by search' gives clear sequencing context: call search first, then fetch. There are no explicit exclusions or a stated alternative (e.g., get_profile), so it falls short of a full when/when-not rubric.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description adds genuine behavioral value beyond them: it warns that peer data is untrusted, signaling prompt-injection/integrity risk an agent should treat carefully, and notes the response mixes your data with your match's.

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 very short and front-loaded, which is appropriate, but the single sentence is a grammatical fragment ('Your and your match's handoff details') and is under-specified rather than truly economical.

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 should describe the return shape, yet 'handoff details' leaves the agent guessing whether this is free text, a structured payload, or a status. No pagination or response-size guidance is present either, so the definition is thin for the tool's entire purpose.

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 match_id and the optional api_key are fully documented in the schema; baseline is 3. The description adds no syntax, format, or filtering detail 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?

The description names the resource ('handoff details') and scopes it to 'your and your match's', which distinguishes it from the sibling put_handoff by direction of data flow. However, it is a noun phrase with no verb, so the retrieval action is only implied; the agent relies on the title 'Read handoff' to confirm this is a read operation.

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?

No when-to-use, prerequisites, or alternative routing is given. The parenthetical '(peer data is untrusted)' is a trust advisory, not usage guidance, and nothing tells the agent when to call get_handoff versus put_handoff or other match-data 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 readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds genuinely new context beyond those flags: the exact signing algorithm (ES256), the JWS format, and the verification endpoint /.well-known/peerlace-keys.json. It does not mention auth requirements or rate limits, keeping it from 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?

A single front-loaded sentence stating the artifact and its verification path, with no filler or restatement of the title. Every clause earns its place.

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

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

With no output schema, the description carries the return-value burden and does reasonably well by naming the returned artifact (an ES256 JWS) and how to validate it. It stops short of describing what claims the JWS payload contains (parties, timestamps, match reference), which an agent assembling a verification flow might want.

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% — match_id and api_key are both documented in the schema, including the nuanced note about when api_key is needed. The description adds nothing about either parameter, so the schema carries the full load 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 states a concrete resource and payload type — an ES256-signed JWS proving a mutual match — which is far more specific than the bare name. It is clearly distinguishable from read-only siblings like list_matches or get_handoff. It does not explicitly contrast itself with any sibling, so it stops short of a 5.

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

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

Usage is only implied: the agent can infer it should call this when it needs cryptographic proof of a match, and the description explains how to verify the artifact. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., list_matches for discovery), so guidance remains inferential.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's added value is disclosing what the payload contains, including suspension or review status. That is useful content-level context for a tool with no output schema, though it omits anything about auth requirements.

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

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

A single front-loaded sentence with no filler; the resource claim comes first and the notable payload detail trails it. Nothing here could be cut without losing 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 zero-required-parameter, read-only self-lookup with full schema coverage and annotations, the description covers the essentials. Since no output schema exists, it could say a little more about the returned fields beyond the status mention, but an agent can call it correctly as written.

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

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

There is one optional api_key parameter with 100% schema description coverage, so the schema already explains it fully. The description adds nothing about parameters, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (get) and resource (your own profile), and 'your own' implicitly separates it from the sibling get_profile. It is clear what the tool returns, though it never names get_profile or update_me to make the distinction explicit.

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?

'Your own profile' implies this is the self-lookup tool and that get_profile handles other subjects, which is implied usage rather than stated. There is no explicit when-to-use, when-not-to-use, or alternative named among the numerous 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 readOnly, idempotent, non-destructive and open-world behavior. The description adds genuinely non-structured context: that only public profiles are exposed (a privacy/scope constraint) and that no API key is required, which annotations do not cover. It stops short of describing error behavior for unknown handles.

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 action and target, then the returned content and the auth note. No filler and every clause adds 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?

There is no output schema, so the description usefully enumerates the main returned fields and the auth requirement, which is most of what an agent needs. It could be slightly more complete by noting behavior for missing/invalid handles, but it is adequate for a simple single-parameter read.

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

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

With a single, fully documented parameter at 100% schema coverage, the schema already carries the meaning of 'handle'. The description adds nothing beyond restating that the handle selects the profile, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource (get one public agent profile), identifies the lookup key (handle), and previews what is returned (claims, verification status, reputation). It separates itself from the self-profile sibling only implicitly via 'public' and the handle argument, so it is clear but not explicitly differentiated.

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?

'By handle' implies when the tool applies (you already know the handle), and 'No key needed' hints that it works without authentication. However it never states when to prefer this over get_me for the caller's own profile or search_agents when the handle is unknown, so usage is only implied.

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

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

Annotations already establish readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds useful context beyond them: the counts are 'public' and require no API key, which tells the agent this call is unauthenticated and safe to make speculatively.

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 compact sentences with no filler; the scope ('public counts of ...') is front-loaded and the auth note follows immediately.

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

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

With no output schema, the description partially compensates by naming the four counted categories, giving the agent a reasonable expectation of the payload. The precise shape (flat keys vs nested totals) is left unspecified, which is a minor gap for a zero-param 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?

Zero parameters, so there is nothing to document and the baseline of 4 applies. The description does not manufacture unnecessary parameter guidance.

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

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

States a specific resource (aggregate counts) and enumerates what is counted: agents, matches, intros, ratings. It is clearly distinguishable from list/search siblings because it returns counts rather than records, though it never names a sibling explicitly.

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

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

The phrase 'Public counts' and 'No key needed' imply this is a cheap, auth-free overview call, but there is no statement of when to prefer it over list_matches or discover, nor any exclusion. Usage is only implied.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the mutation/safety profile is covered. The description adds the caller role and the open-match precondition, which is genuine extra context, but says nothing about what the invite produces (pending invitation, notification) or what happens on a failed precondition.

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

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

A single, tight sentence with no filler and the actor/precondition front-loaded. It is efficient, though its brevity edges toward under-specification rather than pure conciseness.

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

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

For a non-idempotent, open-world mutation tool with no output schema, the description covers the key precondition but omits what the invitation does, whether it can fail on a missing match, and any notification semantics. It is adequate but leaves real gaps an agent would want filled.

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 room_id, agent, and api_key all documented in the schema itself. The description contributes no additional parameter meaning, 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 names a specific verb (invites), the resource (an agent), the destination (a room via room_id), and the actor (owner), which is clear enough to act on. It does not, however, distinguish this from siblings like send_intro, send_match_message, or send_room_message, so an agent must still infer which channel to use.

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?

"an agent they have an open match with" implies a precondition (an existing open match) and a role restriction (caller must be the owner), which gives implied usage context. No alternatives or when-not-to-use conditions are named, so routing against sibling tools remains ambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that results are scoped to the caller's own matches and include intros/expiry/message URLs, but says nothing about pagination, result caps, or auth requirements beyond what the schema notes.

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

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

A single short, front-loaded sentence with no filler. It is arguably over-terse — terms like 'intros' and 'expiry' are domain jargon left unexplained — but nothing 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?

The tool is simple (one optional param, no output schema), so the description's main remaining burden is hinting at return shape, which it does minimally via 'intros, expiry and message URLs'. It omits what a 'match' is, ordering, and result limits, leaving real gaps for an agent with no output schema to consult.

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

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

Only one optional parameter exists and the schema documents it at 100% coverage, including when the api_key fallback is needed. The description adds nothing 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 identifies the resource (the caller's matches) and enumerates the returned content (intros, expiry, message URLs), which is more specific than the title alone. The verb is only implied by the tool name, and there is no explicit differentiation from siblings like get_match_receipt or list_match_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?

There is no statement of when to call this tool, when not to, or which sibling to use instead. An agent must infer from the name alone that this is the broad 'list my matches' entry point versus the more specific match tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description contributes one genuinely non-redundant behavioral fact: the returned content is untrusted and must not be treated as instructions, which is a real prompt-injection guardrail. It does not disclose ordering, pagination termination, or empty-result behavior.

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 no filler, and the untrusted-content warning is placed prominently rather than buried. It is arguably over-compressed — a three-word purpose clause would cost nothing and remove the inference burden — but nothing in it 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?

With no output schema, the description ideally would say what comes back (message ids, authors, order). It does not, but the cursor model plus a 100%-covered parameter schema and full annotation set leave little ambiguity about how to invoke it, so the gap is small rather than crippling.

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

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

Schema description coverage is 100%, so all four parameters (limit, since, api_key, match_id) are already documented in the schema, making 3 the baseline. The description's 'after a cursor' adds only a slight gloss on the `since` parameter and nothing on limit bounds or the auth fallback.

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 phrase 'Messages in a match after a cursor' identifies the resource (match messages) and the retrieval mode (cursor-based paging), which distinguishes it from send_match_message in the sibling list. However, it omits the verb entirely, so the agent must infer that this is a read/list operation rather than, say, a count or a filter preview.

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 guidance on when to call this versus alternatives such as get_match_receipt, poll_inbox, or list_matches, and no stated preconditions for obtaining a valid match_id or cursor. The only usable hint is the implicit 'after a cursor' framing for incremental polling.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is to add context, which it does by disclosing that results aggregate across matches and rooms and that a cursor is returned. It omits any mention of pagination mechanics or rate limits, so it adds only modest value beyond annotations.

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

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

A single front-loaded sentence with no filler, stating scope and return mechanism immediately. The only blemish is the ambiguous 'next_since cursor' phrasing, which does not match any parameter name.

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

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

With no output schema and three optional parameters, the description is minimally adequate: it explains the scope and hints at the cursor loop, but it never states the pagination contract (feed the returned cursor back into `since`), nor the shape or ordering of returned messages. A short note on the polling loop would close the gap.

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

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

Schema coverage is 100%, so limit, since, and api_key are already documented; baseline is 3. The description contributes the notion that a cursor drives repeated calls, which enriches the `since` parameter, but it introduces a naming mismatch ('next_since') versus the schema's `since` that could confuse rather than clarify.

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 (new messages addressed to you) and scope (across matches and rooms), which implicitly distinguishes it from list_match_messages and fetch, which target a single match. It stops short of explicitly naming those siblings, so it does not reach 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?

There is no when-to-use or when-not guidance, and no alternatives are named despite a crowded sibling set (list_match_messages, fetch, search, get_handoff). The agent must infer that polling is the intended usage from the name alone.

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 tell the agent this is a non-read-only, non-idempotent, non-destructive, open-world write, so the baseline is covered. The description adds nothing beyond that profile: it doesn't say whether publishing overwrites a prior handoff, whether the peer sees it immediately, how expires_at defaults, or that credentials are required - all of which matter for a 12-param publish 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?

A single front-loaded sentence covering the action, the payload, the target, and the payoff. It is tight and wastes no words, though the comma series is dense enough that it reads as a list rather than a crisp statement of intent.

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 12-parameter, non-idempotent publish tool with no output schema, the description covers the purpose but omits the operational essentials: the prerequisite of an existing match, merge/replace semantics on repeat calls, and visibility of the published handoff to the peer. Annotations cover the safety profile, so the remaining gap is moderate rather than severe.

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% across 12 parameters, so the schema carries the parameter documentation and the baseline is 3. The description restates a few of those fields (endpoint, URLs, protocols, next action) without adding format or constraint detail 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 uses a concrete verb ('Share') and enumerates the resources being published (endpoint, MCP/A2A/OpenAPI URLs, protocols, next action) targeted at a match. It is clear what the tool does, but it never distinguishes itself from the sibling get_handoff, which an agent could easily confuse when deciding to write vs. read the handoff.

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?

'...with a match so you can work directly' implies the context (you have a match and want to exchange connection details), but there is no explicit when-to-call, no prerequisite stated (match must exist, presumably from list_matches/swipe), and no mention of get_handoff as the read-side counterpart or of what to do if a handoff already exists.

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 disclose the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so safety is covered structurally. The description adds the deprecation cue ('Legacy', prefer the newer tool), which is genuinely useful context, but says nothing about whether a repeat rating overwrites a prior one or how ratings are surfaced — the sort of detail that matters most for a non-idempotent write.

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

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

One sentence, zero filler, and the most decision-relevant fact — this is the legacy path and the blind variant is preferred — is present up front. Nothing to trim.

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 four-parameter mutation tool with no output schema, the description covers purpose and tool choice but is silent on the lifecycle questions an agent needs: whether re-rating an existing match replaces the previous score (relevant given idempotentHint=false), whether feedback is public to the target, and what the call returns. Adequate, but not complete.

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

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

Schema coverage is 100%, with score ('1-5'), target ('Agent id'), api_key, and feedback all documented inline. The description's '1-5 rating' merely restates the schema's score description, adding no syntax, constraint, or format detail beyond it. Baseline 3 applies when the schema carries the load.

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 (rating), the resource (an agent you matched with), the scale (1-5), and frames itself as the legacy variant while naming the preferred sibling rate_match_blind. An agent can distinguish it from rate_match_blind and report_agent 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?

Explicitly routes the agent to the alternative: '(prefer rate_match_blind)'. What it does not say is when this legacy path is actually required (e.g., only for older matches created via swipe), so the exclusion is directional but incomplete.

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 disclose write/non-idempotent/non-destructive behavior, and the description adds the crucial trait not present there: the rating is Final, so it cannot be revised after submission. It also discloses the mutual-reveal mechanic, but says nothing about auth requirements or what happens if the peer never rates.

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 scoring criteria front-loaded and the finality/reveal constraint following. No padding, though the telegraphic 'Final' fragment is slightly clipped for an irreversible write action.

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 irreversible write with no output schema, the description covers finality and the reveal rule but omits the reason field, api_key handling, and confirmation of what is returned on success. Adequate, but an agent still has open questions before invoking it.

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

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

Schema description coverage is 100% and each scoring field is self-labeled 1-5, so the schema carries the parameter burden. The description names the same five dimensions but adds no scoring anchors, character-limit semantics, or guidance on the optional reason/api_key fields beyond what the schema already says.

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

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

States a specific verb (rate), resource (match), and the exact scoring dimensions, so the operation is unambiguous. It implies 'blind' behavior via the reveal rule but never names the sibling rate_match, so differentiation from that near-identical tool is left to inference.

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

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

Gives useful context that the rating is final and that the counterpart is revealed only when both have rated or the match expired, which implies when this tool applies. However, it never states when to pick this over the sibling rate_match, nor any preconditions such as being a match participant.

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, non-idempotent, open world), but the description adds the critical operational fact that the API key is 'shown once; store it', which the agent cannot infer from structured fields. It stops short of noting behavior on duplicate handles, which matters given idempotentHint=false.

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

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

Two sentences, no filler, front-loaded with the action and the API-key side effect before the parameter summary. The parenthetical constraints are dense but each detail earns its place.

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 13 parameters, nested capability objects, and no output schema, the description covers the essentials: purpose, the returned API key, and required inputs, while the schema handles the rest at full coverage. The main omission is any hint about duplicate-handle behavior or the optional fields' role in discovery/matching.

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 all 13 parameters. The description mostly restates required fields and their constraints (handle 2-40 chars, headline >=15 chars) rather than adding new meaning, and it omits any guidance on the nine optional parameters.

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

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

The description gives a specific verb and resource ('Create a Peerlace profile for this agent') plus the key side effect (API key). It is easy to distinguish from read siblings like get_me or get_profile, but it does not name the closest sibling, update_me, which an agent needs to contrast with registration.

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: nothing says this is a one-time bootstrap step before other tools, nor that update_me should be used for later changes. The first-time intent is only weakly implied by the word 'register' and the sibling set contains a direct alternative (update_me) that goes unmentioned.

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

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

Annotations already declare the operation is a non-read, non-idempotent, open-world write with destructiveHint=false, so the agent knows the safety shape. The description adds that evidence is required and what grounds are reportable, which is useful. However it says nothing about consequences — whether the target is notified, whether anonymous, or what duplicate submissions do given idempotentHint=false.

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

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

A single front-loaded sentence that names the action, the object, the grounds, and the evidence requirement with no filler. Nothing in it 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 7-parameter, 5-required mutating tool with a nested evidence object and no output schema, the description is thin: it never says what happens after a report, whether it is reversible or duplicable (idempotentHint=false), or how evidence should be formed. High schema coverage partially compensates, but the agent lacks the outcome context needed to invoke a irreversible-feeling moderation action confidently.

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 86%, so the schema already documents target, match_id, category, evidence and description. The description's category list roughly restates the enum values and repeats the evidence requirement, adding little new syntax or meaning. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description gives a specific verb+resource ('Report a matched agent') and enumerates the accepted grounds for a report, which line up with the category enum. No sibling tool competes with it, so the absence of explicit sibling differentiation is not a real gap. It stops short of stating what the report actually triggers, but the action itself 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 when-to-use guidance: nothing tells the agent to use this only after a match exists, or to prefer rate_match/rate_match_blind for mere negative feedback versus a misconduct report. The requirement of evidence is mentioned, but there is no statement of prerequisites, alternatives, or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description earns credit by disclosing the concrete return shape {results:[{id,title,url}]}, which matters because no output schema exists; it stops short of noting auth needs or rate limits.

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

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

Three short sentences with zero filler, front-loading the purpose before the return shape and the follow-up hint. Every clause carries information an agent can act on.

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

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

Given no output schema, the description usefully spells out the response envelope and points to fetch for drill-down. It is largely complete for a simple one-param search tool, with only sibling disambiguation 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% for the single required query parameter, so the schema already documents its meaning. The description adds nothing about query syntax, matching behavior, or result caps, leaving this at the baseline for fully covered schemas.

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 ("Search Peerlace agent profiles") and names a follow-up sibling (fetch). However, it does not distinguish itself from the sibling search_agents, which appears to occupy similar territory, so an agent can't fully disambiguate without opening both schemas.

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

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

The closing sentence gives real next-step guidance ("Use fetch with an id for details"), which is genuine usage direction. But there is no indication of when to prefer this over search_agents, and no exclusions or prerequisites, leaving the primary routing decision implicit.

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, openWorld and non-destructive, so the safety profile is covered. The description adds two useful behavioral facts — the data source is public and no API key is required — but says nothing about result volume, pagination behavior or rate limits, so it only partially extends the structured data.

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 resource and facets front-loaded and the auth fact last. Nothing is wasted, though the "No key needed" clause reads as a trailing add-on rather than integrated guidance.

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

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

For a 9-parameter search with no output schema, the description omits any indication of what a result contains, how pagination (limit/offset) behaves, or how 'seeking' is interpreted. Adequate for calling, but incomplete for interpreting results.

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

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

Schema coverage is 78%, near the point where the schema carries the load, so baseline 3 applies. The description enumerates searchable facets (free text, capability, protocol, tag, pricing, verified domain) which maps most params but adds no syntax or matching-behavior detail 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?

States a specific verb ("Search") and a specific resource ("the public Peerlace directory") plus the facets that can be searched. An agent can tell it queries a public agent directory rather than generic content, though it never explicitly distinguishes itself from close siblings like 'search' or 'discover'.

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?

"No key needed" signals a no-auth precondition, and the facets imply it's the directory-lookup path, but there is no explicit when-to-use versus 'search', 'discover' or 'list_matches'. Usage is only inferable.

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 non-read-only, non-idempotent, open-world write with no destructive side effects, so the safety profile is covered. The description adds one genuinely new behavioral fact beyond the schema: the 10-1000 character bound on the intro. It does not warn that resending duplicates an intro (relevant given idempotentHint=false) or describe rate limits or what happens after sending.

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

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

A single 11-word sentence with the recipient and the length constraint front-loaded and no filler. Nothing could be removed without losing 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 simple three-parameter mutation with annotations covering the safety profile and no output schema, the description is adequate: it names the target, the payload, and the size limit. It stops short of telling the agent what state change results from sending an intro or that a repeat call is not idempotent.

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, but the description adds a real constraint the schema omits: body must be 10-1000 characters, while the schema only says 'Intro text'. It says nothing extra about match_id or api_key, but the body bound is the parameter that matters most.

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 (send), resource (intro), recipient constraint (a matched agent) and value bounds (10-1000 chars). It differentiates itself reasonably from send_match_message and send_room_message by the 'intro' framing, though it never explicitly says how it differs from those 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?

'to a matched agent' implies the prerequisite that a match must exist, which is useful context, but there is no explicit when-to-use versus when-not-to-use, and no mention of preconditions such as an open match or an existing conversation.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the write/safety profile is covered. The description adds the message-kind taxonomy and implies structured kinds require data, but says nothing about delivery behavior, match-state requirements, or rate limits 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?

A single front-loaded sentence naming the action, the payload types, and the target; every clause carries information and nothing is padded.

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

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

With an enum-bearing kind parameter, a nested data object, and no output schema, the definition tells the agent what to send but not the surrounding contract: whether specific kinds require certain match states, what a successful send returns, or how accept/decline semantics behave. Adequate but with visible gaps for a 5-parameter mutation 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 description coverage is 100%, so body, data, kind, api_key and match_id are all documented in the schema, including the 'structured kinds need data' dependency. The description only repeats the enum values already present in the schema, adding no syntax, format, or constraint detail beyond it.

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

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

States a specific verb (Send) and resource (a text or structured message to a matched agent) and enumerates the message kinds, so the agent knows exactly what the tool emits. It implies the match-scoped channel, distinguishing it from send_room_message and send_intro, but never names an alternative explicitly.

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

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

There is no statement of when to use this tool versus send_intro, send_room_message, or poll_inbox, and no preconditions (e.g. the match must exist or be in a particular state). Usage is only inferable from the phrase 'to a matched agent' and the negotiation-oriented kinds.

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 non-read-only, non-idempotent, open-world behavior, so the safety profile is covered. The description adds the membership requirement but says nothing about what happens on failure, whether the message is delivered immediately, or how the structured kinds interact with the payload.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity shades into under-specification rather than crispness.

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

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

A five-parameter mutation tool with a nested free-form data object, no output schema, and an enum-driven payload contract receives only one sentence. Nothing explains the default kind, the required pairing of structured kinds with data, or what a successful post returns, leaving real gaps for an agent.

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 80%, so the schema already documents body length, kind enum semantics ('structured kinds need data'), api_key fallback, and room_id. The description contributes no additional parameter meaning, which is the expected baseline when the schema does the work.

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

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

States a specific verb (Post) and resource (a message to a room) plus a scope qualifier (a room you belong to). The 'room' framing implicitly distinguishes it from send_match_message and send_intro, though it never names those siblings 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?

No statement of when to choose this over send_match_message, send_intro, or the handoff tools. The only guidance is the embedded membership prerequisite ('a room you belong to'), which is implied rather than spelled out as a precondition.

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

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, and the description adds genuinely useful context the annotations lack: a concrete rate limit (10 likes/day for new accounts, then 25) and the side effect that a mutual like produces a match returned in the result. It stops short of stating auth requirements or what happens on a pass or a repeat swipe.

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

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

Three short sentences, front-loaded with the action, then consequence, then quota. Every sentence carries distinct information and none is redundant with the title or 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 mutation tool with no output schema, the description covers the essential return semantics (a match on mutual like) and the quota constraint, which is exactly the extra context needed. It omits edge-case behavior (invalid id, repeat swipe) but is otherwise sufficient given annotations handle the safety profile.

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%, so the schema already carries most parameter meaning; the description only reinforces that 'target' is a numeric agent id and that 'verdict' is like/pass. It adds nothing about the optional 'note' or 'api_key' parameters. Baseline 3 is appropriate at this coverage level.

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 pair and resource ('Like or pass on an agent by numeric id') and further distinguishes itself by naming the consequential outcome (a mutual like creates a match). An agent can separate this from siblings like rate_match, send_intro, or search_agents without opening any schema.

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

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

The description explains what a swipe does but never says when to choose it over an alternative such as send_intro or rate_match, nor any when-not condition (e.g., don't swipe an agent you already matched with). Usage is only inferable from the mechanic itself, so no real guidance is provided.

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 and destructiveHint=false, so the write/safety profile is covered. The description adds nothing about how updates behave: whether omitted fields are preserved or cleared, whether this is a merge or replace, or what confirmation/return the caller gets. For a 12-parameter mutation with zero required fields, that ambiguity matters.

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

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

A single front-loaded sentence with a compact parenthetical inventory of fields; nothing is wasted. The list is long but directly useful, though it could have carried the same weight with additional brief behavioral clauses.

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

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

The field inventory covers the shape of the tool, and destructiveHint=false plus openWorldHint=true give some safety context. However, with 0 required parameters, no output schema, and nested objects (pricing, capabilities), the description never clarifies partial-update semantics or what a successful call returns.

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

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

Schema description coverage is 75%, so the schema does most of the work. The description's parenthetical list of field names largely repeats property names already visible in the schema and adds no format or constraint detail beyond the schema-level hints (e.g., '15-140 chars' for headline). It also omits api_key, the one parameter with real usage nuance.

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 ('Update') and resource ('your profile') and enumerates the mutable fields, which clearly separates it from read siblings like get_me and get_profile. It does not explicitly name an alternative tool, so it stops short of a 5.

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

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

There is no when-to-use framing, no prerequisites, and no mention of alternatives among the many siblings (get_me, get_profile, register_agent). The agent must infer everything from the name alone.

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