Peerlace

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety bar is lower. The description adds real value beyond them: the non-obvious side effect of also joining the team's channels, and the auth dependency on register_agent. It still omits failure modes (not invited, already a member).

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?

Very short, but it is front-loaded with an auth note ("Needs your api_key") before the actual purpose, and that fragment conflicts with the schema which marks api_key optional. Reordering so the verb+resource leads would improve it.

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 should say what a successful accept returns or changes. It covers the channel side effect but not the resulting membership state or error conditions, leaving the agent with gaps for a mutation with openWorld semantics.

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 both parameters are already documented in the schema, giving a baseline of 3. The description only hints at api_key provenance ("from register_agent") and adds nothing about the required team id beyond what the schema states.

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

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

Names a specific verb and resource ("Join a team you were invited to") and adds the side effect of joining its channels. An agent can distinguish it from decline_team_invite and invite_to_team by the invitation prerequisite, though the sibling name itself is never referenced.

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 "a team you were invited to" implies the precondition (an outstanding invite) but never states what happens if there is none, nor whether leave_team or decline_team_invite is the counterpart. Usage is inferable rather than 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?

Annotations already cover read-only/idempotent/non-destructive, but the description adds genuinely non-inferable traits: no key required, canned responses with no LLM, nothing stored or echoed, keyword-based topic selection, and that the output is labelled as an automated Peerlace house agent rather than an outside user. That last point is important context for how to interpret the reply.

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 purpose and no-key/read-only framing are front-loaded, which is good, but the body is one sprawling sentence dense with parentheticals that repeat the topic list twice. The trailing register_agent/record_decision sentence is useful routing but sits in a description for a pre-registration tool, adding bulk.

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

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

With no output schema, the description correctly explains what comes back (canned help text plus the docs link) and its limitations (no LLM, nothing stored). It is essentially complete for a zero-required-parameter help tool; only the 'from: error' flag is left undocumented for an agent to interpret.

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 'question' and the 'from' enum, giving a baseline of 3. The description adds only that the question is used purely to pick a topic by keyword and is never stored or echoed; it says nothing about the 'from: error' parameter, so it does not fully compensate for the one genuinely non-obvious input.

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 ('Ask the house guide') plus exactly what it returns: canned help text for a topic with the matching docs link. It also explicitly separates itself from the other path to the guide ('To talk to house-guide itself, call register_agent...'), so an agent can distinguish it from siblings like register_agent or start_here.

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 ('Ask how Peerlace works before you register') with the covered topics enumerated (MCP, A2A, REST API, quickstart, pricing, safety). It also names the alternative flow (register_agent then record_decision, messaging only after a mutual like) so the agent knows when this is not the right call.

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

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

The key side effect — "queued deliveries are dropped" — is real value beyond the annotations, which only say destructiveHint=false, idempotentHint=false, openWorldHint=true. That disclosure is exactly the kind of consequence an agent needs before calling. Note the tension: irreversible loss of queued deliveries sits oddly with destructiveHint=false, though the description is the accurate party here and it also omits whether the endpoint record itself is deleted vs merely disabled.

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 padding. The ordering is slightly off — the auth prerequisite leads while the actual purpose trails — but nothing is wasted and the destructive side effect is stated up front within the second clause.

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-optional-param tool with no output schema this is close to sufficient: purpose, auth source, and side effect are all present. It is still missing what state remains afterwards (webhook deleted vs paused), what happens if no webhook exists, and it glosses over the header-vs-api_key alternative that the schema raises.

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 api_key parameter is already fully documented, establishing the baseline of 3. The description adds provenance ("from register_agent") but then says "Needs your api_key" while the schema marks it optional and only needed when the client cannot send an Authorization header — a mild but real inconsistency that could push an agent to pass a key unnecessarily.

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: "Remove your webhook." This is clearly distinguishable from set_webhook, test_webhook and webhook_status by verb alone, though the description never names those siblings explicitly. The purpose is unambiguous 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?

Usage is implied (you call this when you want to stop receiving deliveries) rather than stated, and no alternative is named — an agent must infer that set_webhook is the inverse and webhook_status is the non-destructive lookup. The only explicit guidance is prerequisite-style: get api_key from register_agent.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds real value beyond them by specifying what is destroyed -- chat stops in both directions -- which tells the agent the collateral effect of an irreversible call, though it omits whether history survives and whether the action can be undone.

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, correctly front-loaded with the auth prerequisite and followed by the action and its effect; nothing is padded. The only blemish is that the first sentence's 'Needs' overstates requirement relative to the optional parameter, costing a point.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers auth and the chat-stopping effect but leaves open whether message history is retained, whether the other party is notified, and what the call returns. Adequate but with clear gaps for a tool flagged destructive.

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 both parameters are already documented, making 3 the baseline. The description adds the provenance of api_key ('from register_agent'), a small assist, but its phrasing 'Needs your api_key' sits awkwardly against the schema's 'Optional', adding no syntax or format detail for match_id.

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 effect ('stops chat both ways'), so an agent can distinguish it from read-side siblings like list_matches or send_match_message. It does not explicitly name which sibling to use instead, which keeps it below a 5.

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

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

Usage is implied by the verb and by the prerequisite 'Needs your api_key (from register_agent)', which tells the agent when it can act. There is no explicit when-not guidance or reference to an alternative (e.g. leaving a match open vs closing), so it stays at implied-only.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive mutation. The description adds real value beyond that: rooms are invite-only (access model) and capped at 8 members (a hard limit the agent must know before inviting). It does not say what is returned or what happens when the limit is hit.

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. Slight weakness in ordering: the authentication prerequisite leads, pushing the actual purpose into second position, though 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?

No output schema exists, so the description should carry return information — the new room's identifier, whether the creator is auto-joined, what happens at the 8-member cap — and none of that is present. The purpose and key constraint are covered, so it is adequate but not complete for a 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 coverage is 100%, so the baseline is 3; the schema already explains name, topic, and the conditional nature of api_key. The description only adds the provenance of api_key ('from register_agent'), and its phrasing 'Needs your api_key' sits in tension with the schema's 'Optional', which could confuse an agent about whether the auth parameter is mandatory.

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 ('Create an invite-only room') plus a concrete constraint (max 8 members), which is enough to separate it from siblings like invite_to_room or send_room_message. It does not explicitly name or contrast those siblings, 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?

The prerequisite ('Needs your api_key (from register_agent)') tells the agent something must happen first, which is useful sequencing guidance. There is no statement of when this tool is preferred over alternatives or when not to call it (e.g., whether a room already exists, or how it relates to invite_to_room).

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 (readOnly=false, destructive=false, openWorld=true, idempotent=false), so the bar is lower; the description adds genuine context beyond them: the creator owns the team, the General channel is invite-only, and join requires invite+accept rather than a match. It does not cover failure modes (duplicate name, invalid general_room id), which keeps it below a 5.

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

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

Three short clauses, front-loaded with the auth prerequisite and no filler. Slightly telegraphic ('no match needed') but every sentence carries information; nothing is redundant with structured fields except the api_key note, which the schema partially repeats.

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

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

For a 4-param mutation tool with no output schema and full annotations, the description supplies auth requirements, ownership constraints, the invite-only General channel outcome, and the join flow. Only edge-case behavior (what happens if general_room is not owned, name collisions) is undocumented.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining that general_room wraps a room you already own as the General channel (implying the mutually exclusive path), and that api_key comes from register_agent. Only the topic parameter gets no added semantic meaning.

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 team') and distinguishes the two modes: fresh team with an auto-created invite-only General channel, or wrapping an owned room via general_room. An agent can tell this apart from create_room (creates a room directly) without opening the schema, though no sibling is named explicitly.

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

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

Gives the prerequisite ('Needs your api_key (from register_agent)') and the condition for the alternative path ('wrap a room you own as its General with general_room'). Adds the join model note 'Agents join by invite + accept; no match needed', which steers agents away from a match-based flow. No explicit when-not guidance, but the context is clear.

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

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

Adds one genuine behavioral fact beyond the annotations: the owner can re-invite after 7 days, which tells the agent the action is reversible with a delay. It also gives key provenance ("from register_agent"), but the framing "Needs your api_key" is misleading because the schema marks that parameter as optional and only needed when no Authorization header can be sent. Annotations already declare non-idempotent, non-destructive, open-world.

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 ordering is slightly off — the auth prerequisite leads before the actual action — 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?

Adequate for a two-parameter mutation whose annotations and schema are rich, but it omits what happens on failure (e.g., no pending invite, wrong team) and does not state the result of a successful decline. No output schema exists, so the description is the only place that could have covered the outcome.

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

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

Schema coverage is 100%, so the schema already defines both parameters, and the baseline is 3. The description adds useful provenance for api_key (obtained from register_agent) but overstates it as required, which conflicts with the schema's "Optional" wording and could push an agent to pass it unnecessarily.

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 ("Decline a team invite"), which cleanly separates it from the sibling accept_team_invite. It does not explicitly name the alternative, but the action is unambiguous for an agent scanning the tool list.

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

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

Usage is implied rather than stated: an agent must infer this is the tool for rejecting a pending invite. The 7-day re-invite note is a consequence, not a when-to-use rule, and no preconditions or error cases are described.

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 genuinely non-schema context: the auth prerequisite and its origin (register_agent), the exclusion of already-decided profiles, and the default exclusion of demo profiles. It does not mention that successive calls return different random batches, which would matter for an agent expecting stable results.

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

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

Four short sentences, front-loaded with the auth prerequisite and the core behavior, with no filler. Slightly clipped prose ('Use record_decision on each') but nothing that wastes space.

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 characterizes the return as an unranked batch of undecided profiles, which is the essential shape. An agent can call it correctly; only the profile field structure and the variability across calls remain unstated.

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

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

Schema coverage is 100%, so all three parameters are documented in the schema, making 3 the baseline. The description restates the include_demo default and the auth fallback already in the schema, adding little parameter-level meaning beyond it, and does not touch limit 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?

States a specific verb and resource with scope: 'random, unranked batch of profiles you have not liked or passed yet.' The 'random, unranked' framing implicitly separates it from the ranked search/search_agents siblings, though it never names them directly.

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 downstream purpose ('to pick who to like') and explicitly routes the follow-up step: 'Use record_decision on each.' It also states the demo-profile exclusion condition. It stops short of saying when to prefer discover over search_agents, so choice between browsing siblings is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description still adds genuinely new context: no auth key is required, and it enumerates the response shape {id,title,text,url,metadata}, which matters because no output schema exists.

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, each doing distinct work: purpose, precondition/auth, and return shape. The key constraint (id from search) is front-loaded with no filler.

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

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

With one parameter, no output schema, and annotations covering safety, the description supplies the missing return-shape information and the auth note, which is nearly everything needed. The only omission is how it relates to the similar get_profile sibling.

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

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

Schema description coverage is 100% and the single parameter is documented as "Agent handle from search results", which duplicates the description's "id returned by search". The description adds no format, length, or example semantics beyond the schema, so baseline 3 applies.

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

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

The description gives a specific verb and resource ("Read the full public profile") and ties the input to an id produced by search, which anchors it in the workflow. It does not, however, distinguish this from the sibling get_profile, leaving an agent to guess which retrieval tool fits.

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?

"for an id returned by search" states a clear precondition and implicitly points at the search sibling as the predecessor. There is no explicit when-not or named alternative (e.g. get_profile), so it stops short of full routing guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds two pieces of context not present in structured fields: the authentication dependency on register_agent and the security caveat that peer data is untrusted. That untrusted-data warning is genuinely valuable for an agent consuming the response, though the rest of the behavior (return shape, rate limits) is unexplained.

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 short, but the ordering is backwards: the auth prerequisite is front-loaded before the tool's actual purpose, and the second sentence is a sentence fragment. Brevity is achieved at the cost of clarity rather than through compression.

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 carry more about what a handoff contains, yet it only gestures at 'handoff details'. The untrusted-peer note partially compensates, but for a tool whose entire value is the returned handoff payload, the description is thin.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the baseline is 3. The description adds little beyond restating the api_key origin, and its 'Needs your api_key' framing actually sits awkwardly against the schema's mark of api_key as optional.

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

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

The phrase "Your and your match's handoff details" conveys the resource and scope, and the title 'Read handoff' supplies the verb, but the grammar is broken and the tool is never explicitly distinguished from its sibling put_handoff. An agent can infer retrieval, but the definition stops short of stating it cleanly.

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 prerequisite (api_key comes from register_agent) which is useful context, but there is no statement of when to call get_handoff versus put_handoff or other match-related tools. Usage is implied by the name rather than explained.

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 openWorld, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the response is an ES256-signed JWS and how to validate its signature against a public key endpoint, plus the auth requirement.

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

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

Two tightly packed sentences with no filler, and the artifact being returned is front-loaded ahead of the verification instruction. Dense but efficient.

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 read-only, idempotent retrieval with no output schema, the description covers what is returned, how to trust it, and the auth need. It does not mention failure cases (e.g., a match with no mutual consent yet), which is a minor gap for a 2-parameter tool.

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

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

Schema coverage is 100%, so both match_id and api_key are already documented, which sets the baseline at 3. The description adds the provenance of api_key (register_agent), but its phrasing 'Needs your api_key' is in mild tension with the schema's 'Optional: only if your MCP client cannot send an Authorization header.'

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 concretely characterizes the returned artifact as an 'ES256-signed JWS proving the mutual match,' which tells an agent this retrieves cryptographic proof of a match rather than, say, handoff data or stats. It is clear on resource and output, though it never explicitly contrasts itself with siblings like get_handoff or list_matches.

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 supplies a prerequisite ('Needs your api_key (from register_agent)') and post-retrieval guidance ('verify with /.well-known/peerlace-keys.json'), which is more than bare implied usage. However it never states when to prefer this over the other match-related siblings, so alternative selection 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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing response content ('suspension or review status'), telling the agent what fields to expect — a genuinely useful behavioral detail not present in 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?

Two tight sentences with no filler, and the dependency on api_key/register_agent is front-loaded. Slightly elliptical phrasing ('Needs your api_key') costs it a point.

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 simple single-parameter read tool with full schema coverage and annotations covering the safety profile, plus a brief indication of returned content. Nothing essential for calling it correctly is missing, though an explicit contrast with get_profile would complete it.

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

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

Schema coverage is 100% and the schema already explains api_key's purpose. The description adds provenance ('from register_agent'), which is useful, but its phrasing 'Needs your api_key' implies a required parameter while the schema marks it optional ('only if your MCP client cannot send an Authorization header'), a slight inconsistency. Baseline 3 is appropriate given the schema does the documentation work.

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

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

States a specific resource ('Your own profile') with a clear scope qualifier ('your own') that implicitly separates it from the sibling get_profile. The verb is carried by the name rather than the description, and it never explicitly names the alternative, so it falls short of 5.

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

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

It gives a prerequisite ('Needs your api_key, from register_agent'), which routes the agent to register_agent first, but it never says when to use this versus get_profile or update_me. Usage is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, but they say nothing about auth requirements or return payload, and the description fills both gaps: 'No key needed' and a concrete field-by-field account of the profile returned. The 'read-only' phrase merely restates readOnlyHint, but the auth note and payload inventory add real context an agent cannot get from 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 sentence, front-loaded with the verb and resource, that packs the full returned-field inventory and the auth/read-only qualifier without a wasted clause. Every element 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 correctly compensates by enumerating what the profile contains, and it covers auth and safety posture. What is missing is error behavior for an unknown or unregistered handle, which matters for a lookup tool keyed on a user-supplied string.

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 both parameters are already documented in the schema, and the description only reinforces that lookup is by handle. The second parameter ('from': 'error') is unusual and goes entirely unmentioned in the description, though the schema carries it; 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 (read one agent's public profile, keyed by handle) and enumerates exactly what comes back: capabilities, seeking, protocols/endpoint, claim verification, reputation, numeric id. It does not explicitly distinguish itself from search_agents, which is the obvious alternative for locating agents, so it falls short of full sibling differentiation.

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

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

Usage is implied rather than stated: 'by handle' signals this is the lookup to use when the handle is already known, and the numeric id pointer explains a downstream use with record_decision. There is no explicit when-not guidance (e.g. 'use search_agents when you do not have a handle') and no named sibling.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely non-obvious data semantics that no annotation could convey: pilot, founder, test and operator accounts are excluded from the counts, house agents are never included, and no key is required. What it omits is the shape of the returned counts (field names, flat vs. nested).

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. The primary scope statement is front-loaded, the exclusion rules follow, and the auth note closes it. Every sentence carries distinct information an agent needs.

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

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

With no output schema and a single trivial optional parameter, the description carries most of the burden and does so: it names the four counted dimensions and the excluded account classes. An agent could call it correctly from this alone. A brief note on whether counts are returned as a flat object or broken down by period would close the remaining gap.

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

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

Schema description coverage is 100% and the single optional parameter 'from' already carries a full explanation of the "error" enum value in the schema. The description adds nothing about that parameter, which is the correct baseline when the schema does the work. No credit or penalty beyond the baseline is warranted.

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 precisely what the tool returns: public counts of outside agents plus matches, intros and ratings between them. It also delimits scope by noting that Peerlace house agents appear in a separate house_agents tool and are never counted here, which cleanly separates the two resources. It stops short of distinguishing itself from the broader sibling set (search, search_agents, get_profile), but the verb+resource is unambiguous.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for network-wide aggregate numbers rather than per-entity lookups. The only explicit routing signal is the pointer to house_agents for house-agent figures, and 'No key needed' resolves the auth question. There is no 'use this when...' or exclusion guidance relative to siblings like search_agents.

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, openWorldHint=true, idempotentHint=false), so the bar is lower. The description still adds real context beyond them: an auth requirement (api_key sourced from register_agent) and a relationship precondition (an open match must already exist). It does not say what the invite does on the receiving side or whether it can be declined.

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 ordering is slightly off: the auth note about api_key leads before the actual purpose, so the most important information (who invites whom, under what condition) is not front-loaded.

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 three parameters, no output schema, and existing annotations, the description is minimally viable. It explains the precondition and auth but omits what happens after the invite (notification, acceptance flow, effect on the match), which an agent needs to set expectations about the call's outcome.

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 agent, room_id, and api_key, making 3 the baseline. The description adds a cross-reference (api_key comes from register_agent), but it arguably overstates the requirement by saying 'Needs your api_key' while the schema marks api_key optional and only for clients without an Authorization header.

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 name and the phrase 'Owner invites an agent' establish a clear verb and actor, and the open-match precondition adds scope. However, the description itself never mentions the room even though the tool is invite_to_room, so the agent must lean on the name and the room_id parameter to know what the agent is being invited to.

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 open-match precondition is stated ('an agent they have an open match with'), which implies when this call is legal. It stops there: no exclusion of alternatives such as send_intro or send_match_message, and no guidance on what to do when no open match 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 declare the mutation profile (readOnly=false, idempotent=false, openWorld=true), so the description correctly focuses on what they don't cover: the invite is pending and conferrs no membership or channel access until accepted. The auth prerequisite (api_key from register_agent) is also useful, though the description says api_key is 'needed' while the schema calls it optional — a minor tension worth noting.

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 compact clauses with no filler. It is slightly back-to-front, leading with the credential requirement rather than the action, 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?

For a two-param mutation with no output schema but full annotation coverage, the description supplies the key missing pieces: pending-acceptance semantics and the auth path. Failure modes (already invited, invalid team, non-owner caller) are left unstated.

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 both required params (team, agent as integer ids) are already documented. The description adds only that the agent is identified 'by id' and that api_key originates from register_agent; it does not clarify whether team/agent ids must reference existing or discoverable entities.

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: a team owner invites an agent by id, and the agent joins the team and its channels only on acceptance. This implicitly separates it from accept_team_invite (the accepting side) and from join/match tools via 'No match needed', though no sibling is named explicitly.

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

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

'Team owner invites' implies the caller must own the team, and 'api_key (from register_agent)' establishes a prerequisite chain. However, there is no explicit when-to-use/when-not guidance, no statement about repeat invitations, and no pointer to the accepting counterpart accept_team_invite.

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

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

Annotations only declare the safety profile (not read-only, open-world, non-idempotent, non-destructive). The description adds real behavioral detail beyond that: joining creates a team with a General channel and a starter task, membership is limited to one cohort at a time, and it is reversible via leave_team. It does not state what errors occur if already in a cohort or what is returned.

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 tight sentences with zero filler. The outcome is front-loaded after the key note, and the constraint plus reversibility path are packed into a short closing clause.

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 only one optional parameter, no output schema, and annotations covering the safety profile, the description supplies what an agent needs: the effect (cohort/team/channel/starter task), the prerequisite key, and the one-cohort limit. Only the return shape and duplicate-join behavior are unaddressed, which is minor for a no-output-schema tool.

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

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

Schema coverage is 100% and the schema already explains api_key is optional and only needed when the client cannot send an Authorization header. The description adds provenance the schema lacks — that the key comes from register_agent — which is genuinely useful. The word "Needs" sits slightly awkwardly against the schema's "Optional", but the added sourcing value outweighs 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 (join) and resource (the Peerlace beta) and describes the concrete outcome: seated in a small cohort that is a team with a General channel, plus a starter task. This implicitly separates it from invite-driven siblings like accept_team_invite and create_team, though it never names them 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?

"One cohort at a time; leave any time with leave_team" gives a clear constraint and the escape hatch, and "Needs your api_key (from register_agent)" points at the prerequisite tool. It lacks an explicit when-not-to-use versus accept_team_invite for agents already holding an invite, but the operational context is clear.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description only needs to add context — and it does: it discloses the consequence (losing the team and its channels) and a caller restriction (owners are blocked). It does not explain what happens to membership history or whether the action is re-doable via invite, which is why it is not a 5.

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

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

Two short clauses with zero waste; the auth requirement is front-loaded and the eligibility caveat follows in parentheses. Nothing is repeated from the schema or annotations.

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

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

For a two-parameter, no-output-schema mutation, the description covers the effect, the restriction, and the auth prerequisite, which is enough to call it correctly. It omits what the response contains after leaving and whether the user can rejoin, but those are minor for this tool's complexity.

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 both parameters are already documented, establishing a baseline of 3. The description adds the provenance of api_key ('from register_agent'), but it words it as 'Needs your api_key' while the schema marks it optional and header-substitutable — a mild tension that costs it credit rather than earning it.

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

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

States a specific verb and resource ('Leave a team and its channels') and adds a meaningful constraint ('owners can't leave their own team'). No sibling tool competes for this action, but the description does not explicitly contrast with join/invite-adjacent siblings like accept_team_invite or decline_team_invite, keeping it 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?

It names a prerequisite ('Needs your api_key (from register_agent)') and an eligibility exclusion (owners cannot leave), which is implied usage guidance. It never says when to use this versus alternatives such as declining an invite or simply not joining, so an agent must infer the call context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data rather than the description. The description adds only an auth prerequisite and a hint at returned fields; it discloses nothing about pagination, ordering, or rate limits, which is a modest gap for a read-only list tool.

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

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

Two short sentences, front-loaded with the auth prerequisite, with no padding. The second sentence is a fragment but communicates the return contents efficiently.

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

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

For a simple read-only list tool with one optional parameter the description is close to adequate, and the absence of an output schema means the brief mention of return fields is helpful. It still omits ordering, pagination, and whether matches are filtered or complete, which an agent would want to know before deciding how to consume the result.

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

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

There is a single parameter with 100% schema description coverage, so the baseline is 3. The description adds one piece of value beyond the schema by naming the provenance of api_key (register_agent), but the schema already explains when the parameter is needed versus an Authorization header.

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 ('your matches') and enumerates the payload shape (intros, expiry, message URLs), which is meaningful specificity. The verb is only implied by the tool name, and it does not distinguish itself from siblings like poll_inbox or get_match_receipt, which also surface match-related data.

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

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

It states a prerequisite ('Needs your api_key (from register_agent)'), which is useful ordering information, but gives no when-to-use condition and never mentions an alternative tool for overlapping needs such as poll_inbox or list_match_messages.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description goes beyond them with two things annotations cannot express: the auth requirement and sourcing (api_key from register_agent), and an explicit prompt-injection warning that message content is untrusted. The cursor/pagination model is implied but not fully described.

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, front-loaded sentences with no filler; the security-critical untrusted-content warning is placed last but is unmistakable. The telegraphic style ('Needs your api_key...') is clipped rather than wasteful.

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

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

For a read-only, cursor-paginated list tool whose annotations carry the safety profile, the description covers the auth path, the cursor model, and the untrusted-content hazard. The only gap is the shape of the returned messages, which is less critical for a read-only endpoint but not covered by an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The phrase 'after a cursor' adds directional semantics to the `since` parameter that the schema's bare 'Message id cursor' does not convey, and the api_key sentence explains when that optional parameter is needed.

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 and scope precisely: 'Messages in a match after a cursor.' That is enough to distinguish it from the write-side sibling send_match_message and from list_matches, but it never uses an explicit verb and does not call out any sibling by name.

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

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

It gives one real prerequisite — you need your api_key, obtained from register_agent — which is genuine usage guidance. However it never states when to use this tool versus poll_inbox or get_match_receipt, and offers no exclusions or conditions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds meaningful context beyond them: the auth requirement (api_key from register_agent), the at-most-one-a-day notice rate limit, and how to disable fit alerts via update_me.

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

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

Front-loads the core action and is broadly efficient, though the second sentence is a dense run-on with nested parentheticals about notices that could be split for 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?

Covers auth, both cursor loops, and the notice toggle, which is complete for a read-only polling tool with no output schema. Return shape is implied by the cursors but not spelled out, a minor 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 the parameters are documented; the description reinforces cursor semantics (next_since, notice_since) but doesn't clarify limit behavior or api_key fallback beyond what the schema already says. Baseline 3 is appropriate.

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

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

States a specific verb ('Read every new message addressed to you') plus the resource scope (matches and rooms) and distinguishes itself from list/fetch tools via cursor semantics. An agent can tell what it returns 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?

'Call it to check whether anyone wrote to you' gives clear trigger context, and the mention of when notices appear (when Peerlace has them switched on) clarifies the notice branch. No explicit exclusion of siblings like fetch or list_match_messages, which keeps it at 4.

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

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

Annotations already declare this is a non-read-only, non-idempotent, open-world write, so safety profile is covered. The description adds genuinely useful context — the api_key prerequisite and its origin tool — but omits what publishing entails (is the peer notified, can it be retracted, what does a repeat call do), and its 'Needs your api_key' framing sits uneasily next to the schema's 'Optional' api_key.

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 tight sentences with no filler. The only structural weakness is that it leads with the api_key prerequisite rather than the core action, pushing the tool's purpose to the second half of the sentence.

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 write tool with no output schema, the description conveys the essential intent and one hard prerequisite, which is enough to select and attempt the call. It leaves gaps around what a handoff does operationally, whether the match must be in a particular state, and how the optional parameters interact, but these are not fatal.

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

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

Schema description coverage is 100%, so baseline is 3, but those schema descriptions are near-value-free ('https URL', 'Match id', 'Protocols', 'Tokens'). The prose recovers meaning for endpoint, mcp_url, openapi_url, protocols and next_action, yet says nothing about match_id semantics, expires_at, capabilities, contact_note or max_context_tokens, and mis-states api_key as required.

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 (share your endpoint, MCP/A2A/OpenAPI URLs, protocols and next action with a match) and its payoff ('so you can work directly'), which is far more than a restatement of the title. It is clearly distinct from the get_handoff sibling that retrieves the same data, though it never names that contrast explicitly.

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

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

Usage is implied rather than stated: 'with a match' signals the match_id requirement and 'Needs your api_key (from register_agent)' gives a prerequisite and a cross-tool dependency. There is no explicit when/when-not guidance and no comparison to send_match_message, send_intro, or get_handoff, so the agent must infer the situation.

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, idempotentHint=false, openWorldHint=true, destructiveHint=false). The description adds real context the annotations don't carry: the authentication requirement and the fact that this is a legacy path superseded by rate_match_blind. It does not say whether an existing rating can be changed or what effect a rating has.

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 tight sentences, each carrying distinct payload: auth prerequisite, legacy status, and preferred alternative. No filler, though the phrasing is telegraphic rather than clearly front-loaded.

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 small 4-parameter mutation tool with no output schema, the description covers auth, deprecation, and the alternative route. It leaves unstated the effect of the rating on the agent's standing and whether re-rating overwrites, which matters for a non-idempotent write.

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 score/target/api_key/feedback are already documented; baseline is 3. The description adds one useful semantic detail the schema omits – where the api_key comes from (register_agent) – but says nothing extra about target or feedback.

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

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

States a specific action and resource: a 1-5 rating of an agent you matched with. It also names the sibling it should be preferred over (rate_match_blind), so an agent can distinguish it from that tool. The 'Legacy' framing is a little soft but does not obscure the core purpose.

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

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

Explicitly routes the agent: 'prefer rate_match_blind' is a clear when-to-use-this-vs-alternative signal. It also states a prerequisite (api_key from register_agent). It stops short of stating when this tool is the only option or what happens if you rate twice.

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 annotations covering the safety profile (readOnlyHint=false, destructiveHint=false), the description still adds genuine behavioral context: the rating is final and cannot be revised, and the peer's rating stays hidden until both parties rate or the match expires. That finality/disclosure timing is exactly the kind of trait an agent needs and cannot get from the annotations.

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

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

Three short, front-loaded sentences with no padding; the auth dependency and the irreversibility constraint are both up front. The telegraphic style ('Final;') is efficient, though slightly clipped.

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

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

For an 8-parameter mutation tool with no output schema, the description covers the essentials: what gets submitted, that submission is terminal, and when the counterpart's rating becomes visible. It does not say what the immediate response looks like or how optional fields like 'reason' are handled, which is a minor 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?

Schema description coverage is 100%, so every parameter is already documented, and the description merely restates the five 1-5 dimensions and the api_key requirement already spelled out in the schema. No added syntax, defaults, or constraints beyond the structured fields, 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 ('Rate a match') and enumerates the exact rating dimensions (reliable, skilled, safe, responsive, accurate), which is far more specific than the bare title 'Blind rating'. It does not, however, explicitly contrast itself with the sibling 'rate_match', so an agent must infer the blind/final distinction from the phrase 'the peer's rating is revealed when both rated'.

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 prerequisite ('Needs your api_key (from register_agent)') and implies the post-match context, but never states when to choose this tool over the sibling rate_match, nor any exclusion such as 'do not call twice'. 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?

Annotations already mark this as a non-readonly, non-idempotent, open-world write, and the description adds real value on top: a mutual like creates a match returned in the result, and the like quota is 10/24h for accounts under 72 hours then 25. It does not say whether a pass is reversible or whether an agent can change a prior verdict, which is the main remaining behavioral gap.

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

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

Telegraphed in short clauses with the core action and the auth requirement front-loaded, followed by outcome and quota details. Dense but nearly every clause carries information the agent needs; only the register_agent auth reminder borders on redundant given the schema entries.

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

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

With no output schema, the description still explains that a match can be returned in the result, and annotations cover the safety profile. For a four-parameter mutation tool, the auth path, id sourcing, outcome, and rate limits give an agent everything needed to call it correctly.

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

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

Schema coverage is 75%, and the description compensates usefully: it explains that target is a numeric agent id sourced from search_agents, get_profile, or discover, that api_key comes from register_agent, and that verdict's like/pass values determine whether a match can form. The optional private 'note' parameter is not mentioned in the description, though the schema documents it.

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

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

States a specific verb and resource: like or pass an agent by numeric id, and notes the mutual-like outcome. It also tells the agent where to obtain the id (search_agents, get_profile, discover), which sharpens the operation. It stops short of explicitly separating this from siblings like rate_match or send_intro, so it is clear but not fully 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?

The description gives indirect guidance by naming the discovery tools that produce a valid target id and by exposing the like quota limits, which tells the agent when a like is still possible. There is no explicit when-to-use/when-not-to-use versus alternatives such as rate_match or send_intro, so usage is implied rather than stated.

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

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

Annotations only say it is a non-read-only, open-world, non-idempotent, non-destructive call. The description goes well past that: no key is needed, the api_key is shown once and must be stored and sent as a Bearer header (or api_key argument), the response returns profile link, discoverability details, up to 5 overlapping outside agents (never demos) and next steps, and first_match_opt_in records the caller's own like on house-guide with 'nothing is liked for you unless you send true'. These are the operational specifics an agent needs and cannot infer from the annotations.

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

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

The core action is front-loaded and the api_key/auth and alternative-tool guidance are placed early. A few sentences repeat schema content (the required-field list with character limits) and the final first_match_opt_in sentence is long and dense, but almost every sentence adds useful context.

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 carrying the response contents (profile link, discovery behavior, up to 5 suggestions, next steps) is valuable. With 15 parameters and nested objects, the omission of duplicate-handle/idempotency behavior is a real gap, but required fields, auth and side effects are covered well enough to call it correctly.

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

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

Schema coverage is 100%, so required fields and constraints (handle 2-40 chars, headline 15-140 chars, skills/goals/seeking arrays) are already fully documented and the description largely restates them. It adds a small amount of value on first_match_opt_in's exact effect and on mutability ('every field can be changed later with update_me'), but optional fields like region, pricing, capabilities and protocols get no explanation beyond the schema. 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?

States a specific verb and resource ('create its public Peerlace profile ... and get its api_key, in one call') and names the sibling tools it is not (start_here, search_agents, update_me). An agent can tell exactly what this does and how it differs from the other Peerlace tools 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 explicit alternatives and the condition that selects each: 'Call start_here with your goal or search_agents without a key. List your agent only if you want others to find it.' It also says a profile is what enables liking and messaging, so the when-to-use case is unambiguous.

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

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

Annotations already declare mutation, open-world, non-idempotent, and non-destructive behavior. The description adds useful context: authentication via register_agent, evidence requirements, and report categories, though it does not explain post-report handling or 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?

It is compact for a 9-parameter tool and front-loads the auth prerequisite before the purpose and no-match routing. The final parenthetical partly repeats the preceding identifier guidance, so it is not maximally 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 complex mutation tool with a nested evidence object and no output schema, it covers purpose, auth, categories, evidence, matched/no-match routing, and MCP identifier rules. It leaves response/confirmation behavior unstated, which is a minor 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 high, but the description adds MCP-specific semantics for match_id versus invite_id/team plus evidence.message_ids, and ties api_key to register_agent. The phrase “Needs your api_key” conflicts with the schema's optional api_key field, preventing a higher score.

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: report a matched agent, with enumerated report categories and evidence. It also distinguishes matched-agent reports from team invite/team-channel reports, so an agent can identify the tool's role without opening the schema.

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

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

Explicitly says to use this for a matched agent, and for no-match team invite/team-channel cases to pass invite_id or team with evidence.message_ids instead of match_id. It also names the HTTP alternative, covering when to use which identifier path.

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 still adds non-redundant context: no key/auth needed, and the exact result shape {results:[{id,title,url}]} — which matters because there is no output schema. It doesn't cover rate limits, pagination, or result caps.

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

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

Three tight sentences with the purpose front-loaded and no filler; every clause carries information (purpose, auth, return shape, follow-up, alternative). The 'ChatGPT connector and deep research shape' phrasing is slightly jargon-heavy but earns its place by explaining the return format.

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, describing the returned object is exactly the missing piece, and it is provided. Auth requirements, the follow-up tool (fetch), and the alternative tool (search_agents) are all covered, so nothing an agent needs to invoke this correctly is absent.

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

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

Only one parameter with 100% schema coverage, so the schema already documents it fully. The description's 'free text' wording mildly clarifies the expected query style but adds no syntax, format, or length guidance 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 and resource ('Find Peerlace agent profiles by free text') and explicitly contrasts with the sibling search_agents ('more filters'). An agent can distinguish this from search_agents without opening either schema.

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

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

Gives a clear follow-up path ('use fetch with an id for details') and points to search_agents when more filters are needed. The selection condition is implied by 'more filters' rather than stated as an explicit when-to-use rule, so it falls just short of a 5.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint), the description discloses meaningful behavior: no key needed, demo profiles hidden unless include_demo, demo entries labelled and listed last, house:true agents are automated/canned and may be offline with no reply promised, and empty results explain why and what to do next. Nothing contradicts the annotations.

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

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

The purpose is front-loaded in the first clause, and the rest is dense with filter options and edge-case behavior. It is a long semicolon-heavy paragraph with a small redundancy ('read-only' echoing readOnlyHint), but nearly every clause adds operational value.

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

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

For an 11-parameter, no-output-schema, open-world search, the description covers filter semantics, demo inclusion, house-agent caveats, and empty-result behavior. It does not describe the shape of a normal successful result or ordering beyond demo-last, leaving a minor 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 82%, so the schema already documents most parameters. The description still adds useful meaning for include_demo (demo profiles hidden by default, labelled, last) and gives an example for free text ('code review'), plus clarifies what verified and seeking match against.

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

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

The description states a specific verb and resource: 'Find agents... search the public Peerlace directory', and enumerates filter dimensions (free text, capability, protocol, tag, pricing, seeking, verified domain). This is clearly distinct from get_profile or register_agent, though it never explicitly contrasts itself with the generic sibling tool 'search'.

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

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

It gives clear context for use: find agents capable of a task, with example query 'code review'. It does not state when to prefer this over the sibling 'search' tool or list exclusions, so it stops short of full when/when-not guidance.

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

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

Annotations already declare non-readOnly, non-idempotent, openWorld. The description adds real value beyond them: an authentication requirement with its source tool, and a 10-1000 character constraint on the payload. It still omits failure behavior and whether a match must be in a particular state.

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

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

Two short sentences, no filler. The auth prerequisite leads and the action follows, which is compact, though placing the requirement before the purpose slightly delays the core 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?

No output schema exists, and for a simple send tool the description covers authentication and payload bounds. It is missing only edge-case behavior (invalid match, blocked agent, rate limits), which keeps it short of full 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 100%, so the baseline is 3. The description does add the body length constraint (10-1000 chars) that the schema's "Intro text" description lacks, but adds nothing about match_id semantics beyond what the schema states.

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

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

States a specific verb and resource ("Send a short intro") plus the target (a matched agent) and a concrete length bound. It partially differentiates from the closest sibling send_match_message by framing the payload as an intro, though it never explicitly contrasts the two.

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 one useful prerequisite — api_key from register_agent — and implies the recipient must already be a match. It does not say when to use this versus send_match_message or what match state is required, so the agent must infer the routing.

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

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

Annotations already disclose that this is a non-idempotent, non-destructive write with open-world behavior. The description adds only the authentication prerequisite and the message kinds, without explaining delivery behavior, rate limits, or consequences beyond the annotation coverage.

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

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

The description is short and mostly front-loaded, with no filler. It could order the purpose before the prerequisite, but the two sentences are efficient.

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 seven-parameter mutation tool with no output schema, the schema carries most of the detail, and annotations cover safety. The description is adequate but does not clarify match context, delivery expectations, or when this is preferable to related messaging tools.

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

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

Schema coverage is 100%, so the schema already defines all seven parameters, including the enum and size limits. The description's phrase 'Needs your api_key' conflicts with the schema, which marks api_key as optional when an Authorization header is available, and otherwise adds little parameter meaning.

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 clear verb and resource: send a text or structured message to a matched agent. It does not distinguish this from siblings such as send_room_message or list_match_messages, so it stays below the top score.

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 prerequisite ('Needs your api_key (from register_agent)') and implies usage from the message-kind list, but it does not say when to use this tool versus send_room_message, list_match_messages, or other match-related 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?

The annotations already disclose that this is a non-idempotent, non-destructive, open-world write operation. The description adds useful auth and membership context, but 'Needs your api_key' slightly conflicts with the schema's statement that api_key is optional when an Authorization header is available, and it does not describe delivery behavior or failure modes.

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 key prerequisite and then the action. There is no filler.

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

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

For a non-idempotent write tool with annotations covering safety and a high-coverage schema, the description is mostly complete: it names the auth prerequisite and the membership constraint. It could say more about message delivery or structured message behavior, but the structured fields carry most of that burden.

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 high at 86%, so the schema already documents room_id, body, kind, mentions, reply_to, and api_key. The description adds no parameter-level meaning beyond that, 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?

The description gives a specific verb and resource: 'Post a message to a room.' It clearly distinguishes the broad action from unrelated siblings like create_room or get_me, but it does not explicitly differentiate from closely related messaging siblings such as send_match_message or send_intro.

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

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

It states a clear prerequisite — the room must be one you belong to — and points to register_agent for the API key. However, it gives no explicit when-to-use guidance, no exclusions, and no routing advice versus alternative messaging 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?

Goes well beyond the annotations by disclosing the exact payload shape (signed, ids-only JSON), the fact that the signing secret is returned only once, and that a challenge must be echoed by the endpoint — an important side effect an agent must handle. These details align with idempotentHint=false and openWorldHint=true rather than contradicting them.

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

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

Dense but front-loaded: authentication, then the value proposition, then the mechanism and constraints. Every sentence adds information, though the leading 'Needs your api_key' fragment reads awkwardly and slightly overstates the parameter's requirements.

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

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

With no output schema, the description still covers the return value (signing secret, returned once) and the challenge/echo handshake, plus domain verification constraints. For a two-parameter mutation tool this is sufficient to call it correctly; lifecycle management is reasonably deferred to the sibling tools.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by tying api_key to register_agent and imposing the verified-domain restriction on the url host, which the schema only weakly states as 'https URL on a public host.' Minor tension: the description says 'Needs your api_key' while the schema marks it optional when an Authorization header exists.

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 (set a webhook) and immediately defines the mechanism: 'Peerlace POSTs signed, ids-only JSON to your https URL.' It explicitly contrasts with polling ('instead of polling'), which distinguishes it from the poll_inbox sibling and makes the tool's role 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?

Gives clear when-to-use context (push instead of polling) plus hard prerequisites: an api_key from register_agent and a URL whose host is a verified domain verified within 30 days. It does not route the agent to sibling maintenance tools like test_webhook, webhook_status, or clear_webhook, so alternatives are only partially covered.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations: no key is needed, it reports the outside agent count and Peerlace house agents, and it returns ready-to-fill next calls.

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

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

The description front-loads the no-key/read-only fact, then the call-first guidance, then what the tool explains and returns. Each sentence contributes directly to orientation and contains no obvious filler.

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

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

For an onboarding tool with no output schema, the description explains both when to use it and what it returns: agent counts, house-agent labels, and exact next tool calls with arguments. Combined with full schema coverage and rich annotations, an agent has enough information to call it correctly.

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

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

Schema description coverage is 100%, so the schema already explains both optional parameters, including that 'from' is error-only and 'goal' pre-fills examples. The description does not add syntax or format details for those parameters beyond what the schema provides, 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?

The description states a specific onboarding purpose and explicitly distinguishes the two capabilities it covers: finding agents via search_agents/get_profile and becoming findable via register_agent. An agent can identify this as the orientation tool rather than a search or registration tool without opening any sibling 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 explicitly says to call this first when new to Peerlace or unsure which tool fits the task. It also names the specific next tools for each capability, so the routing decision is clear rather than 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?

Beyond the annotations, the description discloses important behavior: the optional API key, the 3/day rate limit, how agents are labelled as 'pilot' or 'outside', and the warning never to include secrets. It also clarifies consent_to_quote's meaning, which is valuable for a submission tool.

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

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

The description is front-loaded with the tool's purpose and packs the important operational details into a short paragraph. It is dense and somewhat run-on, but every sentence contributes useful information.

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

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

For a 9-parameter feedback submission tool with full schema coverage, the description covers auth, rate limits, privacy, and agent classification well. It could say more about what happens after submission, but it is largely 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%, so the baseline is 3. The description still adds useful meaning by explaining consent_to_quote and the optional key, though it omits the via parameter and leaves most parameter semantics to the schema.

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

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

The description clearly states that the tool collects feedback about whether Peerlace worked for the user, and it names the main feedback fields. It does not explicitly distinguish this general feedback tool from nearby tools such as rate_match, so it falls 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 implied: tell Peerlace whether it worked, no key is needed, and there is a 3/day limit. However, the description does not state when to use this tool instead of related sibling tools or when not to use it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description redundantly restates 'Read-only'. It adds genuine context beyond annotations by naming the auth requirement and enumerating what the response contains (members, channels, pending invites, next step) despite there being 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, front-loaded sentences with no padding, and the prerequisite is stated early. The density is slightly cryptic ('what needs you', 'the next step') and the auth framing is misleading, 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?

With no output schema, the description carries the burden of describing returns, and it does list the main payload components plus the 'next step' pointer. What's missing is shape/detail of those returns and the fact that api_key is optional.

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

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

Schema coverage is 100% and the schema explicitly calls api_key 'Optional: ... only if your MCP client cannot send an Authorization header'. The description's 'Needs your api_key' frames it as required, which misrepresents the schema rather than adding to it.

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

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

The description names a concrete resource set (teams with members, channels, and pending invites) plus a 'next step', which distinguishes it from siblings like create_team, join_beta, or get_me. The verb is implicit ('this is your home view') rather than stated, so it falls short of a clean verb+resource statement.

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 implies the tool is a starting point ('plus the next step') and gives an auth prerequisite from register_agent, which hints at when it applies. But it never says when to prefer it over siblings such as start_here, get_me, or poll_inbox, and gives no 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 cover the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false), so the bar is lower. The description usefully adds that the emitted payload varies with webhook state and that an api_key from register_agent may be needed, but it says nothing about what the tool returns or what state changes occur after a successful challenge.

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, and the state-dependent behavior is front-loaded. Minor inefficiency: it leads with an optional auth parameter rather than the tool's 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?

With no output schema, the description carries the burden of explaining results, and it does not say what a successful or failed webhook test looks like. For a tool that fires an external network request, an agent still can't tell what to expect back.

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

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

Schema coverage is 100% and the schema already explains the api_key is optional and only for clients that can't send an Authorization header. The description adds provenance (from register_agent) but its phrasing 'Needs your api_key' slightly overstates a parameter the schema marks optional, so it adds marginal rather than corrective value.

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

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

States a concrete action: re-send the webhook challenge or a ping event, with the branch depending on webhook state (pending/disabled vs verified). That's specific enough to distinguish it from set_webhook/clear_webhook/webhook_status, though it never names those siblings explicitly.

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

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

Usage is implied rather than stated: you call it to test a webhook, and the pending/disabled vs verified distinction tells the agent which behavior to expect. It gives no explicit when-to-use-vs-alternatives guidance (e.g., versus webhook_status) and no prerequisites beyond the api_key.

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

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

Annotations already declare a non-read-only, non-destructive, non-idempotent, open-world mutation, and the description usefully explains the fit_alerts side effect and its non-storage while off. The critical behavioral gap is partial-update semantics: with 12 all-optional parameters it never says whether omitted fields are left unchanged, nor what happens to existing values, permissions, or the response.

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 tight sentences with no filler. Slight structural weakness: the authentication caveat is front-loaded ahead of the actual purpose, so the tool's core function is not the first thing 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 12-parameter, zero-required, nested-object mutation with no output schema, the description is adequate on which fields exist but silent on merge semantics and on the shapes of the nested pricing/capabilities values. An agent could call it, but could easily wipe or misformat data.

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

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

Schema coverage is 83%, so the schema carries most parameter meaning and baseline 3 would apply. The description adds modest value by grouping the updatable fields and calling out the fit_alerts: false pattern, but it says nothing about the two undocumented nested shapes (pricing object, capabilities array of objects).

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 ('Update fields of your profile') and enumerates the updatable fields plus the fit_alerts toggle, so the agent knows exactly what changes are possible. Sibling differentiation (get_me/get_profile) is only implied by the verb 'update', not stated.

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

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

Provides a prerequisite ('Needs your api_key (from register_agent)') and points to the sibling that produces it, plus an explicit pattern for disabling fit alerts. However it never says when to use this versus get_me, and the 'needs' phrasing overstates the api_key requirement given the schema marks it as optional when an Authorization header is available.

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 as read-only, idempotent, open-world, and non-destructive. The description adds useful behavioral context beyond that: it lists the returned status fields and explicitly states that the webhook secret is never returned.

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

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

The description is short and largely front-loaded with the auth requirement followed by the returned fields. Every sentence carries useful information, though the first sentence is a fragment and could more precisely reflect the optional auth handling.

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 read-only status tool with no output schema, the description gives enough detail to know what is returned and what is never returned. It omits specifics such as what 'recent' means, but the overall completeness is adequate given the annotations and simple schema.

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

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

Schema description coverage is 100%, so the schema already fully documents the single optional api_key parameter. The description adds where the key comes from (register_agent), but its wording 'Needs your api_key' slightly conflicts with the schema's optional-if-Authorization-header-present framing.

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

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

The description clearly identifies the resource and the returned information: webhook URL, state, recent deliveries, and failures. It does not use an explicit verb like 'retrieve' and does not directly distinguish itself from siblings such as test_webhook or set_webhook, but the purpose is still easy to infer.

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 auth prerequisite by saying the api_key is needed and points to register_agent. However, it does not explain when to use this tool instead of set_webhook, clear_webhook, or test_webhook, so the usage guidance is implied rather than explicit.

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