hunchful

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

Annotations only cover safety flags (readOnly=false, idempotent=false, destructive=false); the description adds genuinely new behavior: the three AI consent settings and what each does, plus the hard rule that households with a minor always produce a draft. That is exactly the kind of outcome-level detail an agent cannot infer from structured fields.

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

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

Front-loads the action, then the examples, then the consent rule — no filler sentences. The consent clause is dense and slightly packed into one long sentence, which costs a little readability 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 an output schema present, return values need no explanation, and the description covers the non-obvious behavior (consent routing, minor safeguard) that the schema and annotations cannot. What is left implicit is duplicate handling and permission requirements, which a mutation tool would ideally state.

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 date/time/title/household formats are already documented (YYYY-MM-DD, HH:MM, 'Dentist (Alva)', list_households names). The description's examples echo the schema rather than adding new syntax or constraints, 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 ('Put an event in the household calendar') and grounds it with two concrete examples, which lets an agent separate it from siblings like create_event, add_hunch, or add_session without opening any schema.

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

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

Gives a clear usage constraint ('only what the person asked for') and explains the consent gate that decides whether the event is drafted, sent, or refused. It stops short of naming an alternative tool or explicitly contrasting with create_event/read_household_calendar.

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 supply the safety/idempotency flags; the description adds the load-bearing behaviors: owner-level authorization required, the record is visible/revisable/removable by the person, and the agent must not invent or infer a hunch. The 'NEW' framing also matches idempotentHint=false coherently.

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 tightly packed sentences, front-loaded with the core action and constraints, with the alternative tool named last. No filler or restatement of the title.

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?

An output schema exists, so return values need not be described. Between the description (auth, naming, confirmation rule, alternative) and the schema (8 params, enums, ranges), an agent has 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 already 88%, so the baseline is 3, but the description adds real semantics beyond it: a naming convention for situational axes ('When <situation>') and a constraint that 'pole' must reflect what the person actually said, not a model inference. The by/editToken/modelId parameters remain schema-documented only.

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

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

States a specific verb and resource — recording a newly confirmed hunch as a custom axis added to the person's model — and explicitly frames it as NEW versus an unanswered prompt. It is clearly distinguishable from suggest_question and read_model without opening a schema.

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

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

Gives the selecting condition for both directions: use this when the person has just confirmed an answer, use suggest_question instead if they haven't answered yet. It also states prerequisites (owner-level trust via OAuth or editToken) up front.

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 safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description usefully adds that nothing is written directly — it always produces a Stream card the user must tap, and that it only fires on request. That mechanism is behavior an agent could not infer from annotations alone.

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

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

Three short sentences, front-loaded with the core action and ending with the guardrail. The parentheticals and Swedish terms add local color without bloating it, though "ALWAYS" capped and the mixed-language examples are slightly noisy.

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 10 parameters, full schema coverage, an output schema, and annotations present, the description only needs to establish intent and the suggestion-card behavior, which it does. Series-specific parameters (repeat/until) are left entirely to the schema, which is acceptable given its richness.

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 each parameter is already well documented, setting the baseline at 3. The description adds only marginal value, clarifying that "kind other" maps to a match/show/förhör test day, which is a small semantic gain over the enum.

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 (suggest a new session) and scopes it to groups the person leads, distinguishing one-off events from weekly series. It does not explicitly differentiate itself from the sibling change_session, but the noun/verb pairing is unambiguous on its own.

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

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

"Only when they ask" gives a clear triggering condition, and the description conveys the mechanism (a suggestion card the user taps to confirm) rather than a silent write. No explicit when-not or named alternative, so it stops short of a 5.

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

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

Goes well beyond the annotations: discloses dedup behavior, that recently-bought items are resurrected, and a full three-mode consent model ('draft'/'send'/'off') plus the under-18 always-draft override. This is exactly the behavioral context the annotations (readOnly=false, destructive=false, idempotent=false) cannot carry. The dedup line has mild tension with idempotentHint=false, but the resurrection semantics make the overall behavior genuinely non-idempotent, so it is not a contradiction.

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 dedup behavior, then the consent model; every sentence carries load. The semicolon-chained consent sentence is dense but each clause is needed given the branching behavior.

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?

An output schema exists, so return values need no explanation, and the description fully covers the non-obvious behaviors (dedup, resurrection, consent gating, minor-safety override). Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (items, household) are already fully documented in the schema, including the 1–20 count and the single-household omission rule. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Put things') and resource ('the household's shopping list') with a scope qualifier ('only what the person asked for'). An agent can distinguish this from read_shopping_list or check_shopping_items without opening any schema.

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

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

The '— only what the person asked for' clause constrains when to add, and the consent paragraph explains when an add actually takes effect, which is useful. But it never names or routes to alternatives (read_shopping_list, check_shopping_items), so sibling 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=false, destructiveHint=true, and idempotentHint=true. The description goes further by disclosing consequences beyond the annotation surface: approvals notify the requester while declines are silent, and answering is gated by the target's consent policy. It stops short of covering auth/scope or rate behavior, but adds real value.

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 action is front-loaded in the first clause, and every sentence carries non-redundant information. The heavy parenthetical nesting (em-dash clause plus embedded example quote) makes it denser than ideal, though nothing is filler.

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

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

With an output schema present, return values need not be described, and the consent/confirm requirements are well covered. For a destructive, consent-gated mutation the description supplies enough context to call it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds workflow meaning on top of the schema, particularly the confirm:true precondition and the differing effects of 'approve' vs 'decline', which the enum alone does not convey.

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

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

States a specific verb pair (approve/decline) plus resource (one follow request) and cardinality, so an agent can separate it from list_follow_requests at a glance. The 'Channels:' title prefix also scopes it correctly.

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 constraints ('ONLY with their own answer', 'only with confirm: true'), prescribes the ask-first workflow with a sample prompt, and lays out the 'friends' policy branching (draft/send/off). This is a rare, near-complete when-to-use and how-to-use spec.

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

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

Annotations declare this is a non-read, non-idempotent, non-destructive write; the description adds real value beyond them by disclosing the authorization requirement (OAuth or editToken) and the semantics of the write (appends evidence pointers, nudges confidence, one logged revision). It stops short of describing reversibility or rate/limit behavior, keeping it out of the top band.

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, front-loaded with the core action, followed immediately by the routing rule and auth note. No filler or restatement of the title.

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?

An output schema exists so return values need not be explained, and the description covers auth, effect, and the sibling alternative. What remains thin is the per-item payload semantics (why up to 50 items, how evidence maps to a revision), which the description leaves to the schema.

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

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

Schema coverage is only 33%, so the schema does not carry the burden alone. The description explains editToken via the auth sentence and implicitly covers 'direction' through 'nudge confidence', but patternId, source, and observedAt semantics come entirely from the schema, and the description adds no syntax or constraints for them.

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 ('Apply a refinement') plus the concrete effect ('one logged revision ... append evidence pointers, nudge confidence'), so the agent knows exactly what happens. The modifier 'directly' distinguishes it from the propose sibling without needing to open 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?

Explicitly routes the agent: 'Prefer propose_refinement unless the owner asked for direct writes.' Names the alternative and the condition that selects this tool instead, and adds the auth path (OAuth own model or editToken) needed to actually invoke 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 destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=false, but the description adds substantial context: it ends the friendship, closes the conversation, the other side is not told, cannot be undone from here, and requires confirmation. This is richer than the structured hints.

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 tightly written sentences front-load the action and condition, then side effects, then prerequisite and alternative. No sentence is redundant or meandering.

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?

An output schema exists, so return values need not be explained, and the description covers the dangerous side effects, irreversibility, notification behavior, confirmation requirement, and alternative tool. The only gap is conversationId discovery/format, which is minor but leaves one parameter underspecified.

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

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

Schema coverage is 50%: confirm has a schema description, but conversationId has none. The description reinforces the confirm workflow ('ask the person, then call with confirm: true') and implies conversationId scopes the block, but it does not document conversationId's format, source, or semantics, leaving half the parameters underspecified.

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 (block) and resource (the other person in a conversation), and distinguishes itself from sibling flag_conversation by naming that alternative. The purpose is immediately clear and not tautological.

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 gives when to use it ('when the person asks or clearly wants it') and names the alternative for danger ('use flag_conversation — always allowed'). It also supplies the required confirmation sequence ('ask the person, then call with confirm: true').

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=false, idempotentHint=true, destructiveHint=false), the description discloses the actual write mechanism and blast radius: it always produces a card in the person's Stream, the tap is what commits the change, and the notify set includes players, parents who asked to be told, and the carpool, plus the group-chat message. That explains why the operation is non-destructive/idempotent (a cancelled session can be restored) and is genuinely beyond what the structured fields convey.

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

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

Front-loaded with purpose, then mechanism, then session-selection, then the usage gate — a sensible order. It is a single dense paragraph with several em-dash asides and the vague phrase 'through every check the app has', so it is readable but 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description covers all four modes, target identification, notification side effects and the usage gate, but says nothing about failure/preconditions (what if the person does not lead the group) or how long the Stream card remains actionable.

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

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

With 100% schema coverage the baseline is 3, and the description does add real meaning: the message is sent in the person's own voice and appears in the group chat as theirs, and 'Leave out to only notify' clarifies message optionality. However, it states the message is '≤ 500 characters' while the schema allows maxLength 1000, a conflicting limit that could cause an agent to reject valid 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+resource immediately: suggest moving/cancelling/changing the place of one session of a group the person leads, or restoring a cancelled one. It is unmistakably distinct from neighbors like add_session (create), message_group (plain messaging) and read_schedule (read), and the title's word 'suggest' is immediately clarified by 'the tap makes the change'.

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 gate ('Only when they ask') and tells the agent how to identify the target session: by `key` from read_schedule, or by `sessionDate` (+ `sessionTitle`). It does not explicitly name the sibling to use instead when the intent is a brand-new session or a pure broadcast, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: outputs are aggregate numbers only and never identify individuals, and teen-run or youth channels report positive totals only. 'Read only' merely restates the annotation, but the privacy rule and youth-channel quirk are real added value.

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 dense paragraph, front-loaded with 'measured in MEETUPS first' so priority of metrics is clear before the enumeration. It is long and somewhat run-on, but nearly every clause carries substantive information about output content or constraints.

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

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

With an output schema present, return values need no explanation, yet the description still sets expectations about metric composition and trend comparison. Annotations handle the safety profile and the description handles scoping, privacy, and edge cases, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100%: period enum and channel resolution (channelId, @name, or name, omittable when exactly one channel exists) are fully documented in the schema. The description adds no parameter-level detail such as default period semantics beyond what the schema states, so the baseline 3 applies.

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

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

The description names a specific resource (one of the person's channels) and a specific measurement (reach), then enumerates the exact metrics returned: event attendance and first-timers per event and per month, sign-ups, views, unique people, reactions, and period-over-period trend. No sibling tool produces channel aggregate stats, so an agent can confidently select this one.

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: the agent can infer you call this to see how a channel is reaching people over the last 7d/28d. There is no explicit when-to-use/when-not, and no sibling is named as an alternative, although the schema points to list_my_channels for obtaining the channelId.

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 non-read-only, idempotent, non-destructive; the description adds far more — the reversible toggle semantics, the source of IDs, and a full consent model with draft vs send vs off and a hard under-18 rule. This is behavioral context the structured fields do not carry.

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

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

Front-loaded with the action and toggle behavior before branching into the consent detail. Dense but every clause (done: false, itemIds source, consent states, under-18 rule) is load-bearing, though the consent sentence is long.

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

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

With an output schema handling return values, annotations covering the safety profile, and the description covering invocation conditions, ID sourcing, and consent gating, an agent has everything needed to call this correctly or correctly decline.

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 done, itemIds, and household are already documented in the schema. The description reinforces done: false and itemIds' origin but adds no format or edge-case detail beyond that baseline, and never mentions the optional household parameter.

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 (tick items off the household's shopping list) and explicitly covers the inverse operation via done: false. It also names where itemIds come from (read_shopping_list), so the agent can distinguish it from add_shopping_items and read_shopping_list at a glance.

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 usage condition — 'Only when the person says they bought them' — and names the sibling that supplies the required itemIds. It also spells out the consent gating (draft/send/off and the under-18 override), which tells the agent exactly when this may proceed.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description goes well beyond them: Messages-permission gating of preview lines, hard exclusion of content written by under-18s, threads returned as COUNTS only, and the "not open yet" state of the pro inbox. These are genuine behavioral constraints an agent could not infer from structured fields.

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

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

Front-loaded with the one-line pitch before the detail, which is good. However, it then enumerates the entire return surface (identity, week, threads, pending, badge) in a single dense run-on even though a full output schema already exists, so much of that clause stack is duplicative rather than additive.

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 no-parameter aggregator with an output schema, the description covers everything an agent needs: what is included, what is deliberately excluded (under-18 lines, pro inbox), the privacy precondition, and the follow-up cursor for `events`.

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

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

Zero parameters, so there is nothing to document and the baseline is 4. The description correctly spends no effort on inputs.

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 aggregate resource (the person's whole day: identity, personas, week, open threads, pending answers, badge count) and explicitly positions itself as the entry point against the list_*/whats_waiting siblings. An agent can tell it apart from `events` because the description says it returns the `next` cursor for that tool.

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

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

"Start every session here" is an explicit directive for when to call it, and the `next` cursor note tells the agent to poll `events` for later changes. It stops short of naming when NOT to use it or which sibling supersedes it for a specific slice (e.g., whats_waiting vs this).

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 only safety flags, the description supplies the behavior that matters: a draft card in the Stream by default, immediate publish gated on both an app permission ("May publish directly") and an under-18-visibility condition, plus the side effect that followers are notified once. That is well beyond annotation coverage, though error/rate-limit behavior is still unstated.

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

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

It is reasonably short and the purpose clause leads, but the style is oblique — "reach is measured in who comes" and the em-dash clause about "its channel's event" cost parsing effort without adding usable information. The publish-gating sentence, by contrast, earns its length.

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

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

For an 8-parameter mutation with nested objects, an output schema and 88% schema coverage, the description covers purpose, eligibility constraints, consent and default draft/publish behavior. The only gap is that it does not tell the agent when to prefer this over the household-event or post siblings.

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 88%, so the schema already explains as, mode, place, title, startsAt, endsAt and capacity in detail. The description mainly restates the mode default and the place restriction rather than adding format or interaction rules the schema lacks, so it sits at the baseline when the schema does the heavy lifting.

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

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

The description states a concrete verb and resource — create an event for a group/channel the person runs, covering sign-ups, waitlist and reminders — which is more specific than the title. It gestures at a sibling ("Like create_post") but only as an analogy for the draft workflow, not as a disambiguation from the closer sibling add_household_event, so an agent still has to infer which event tool applies.

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 explicit consent rule ("Only when they ask") and hard eligibility limits (free events only, public place or venue, never a private home), which is real usage guidance. However it never names an alternative tool or an exclusion such as "use add_household_event for household-only events", so the routing between siblings remains inferred.

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

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

Adds substantial context beyond the annotations: it discloses that the new code replaces the previous one, that it is valid for 30 days, that it can be shared as text or a URL, and that use of it produces a friend request requiring approval. The annotations only carry safety flags, so this lifecycle detail is genuinely additive.

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

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

Front-loaded with the core action and constraints, and every sentence serves a purpose (replacement, validity, sharing, downstream effect, gating). The middle sentence describing the sharing/approval flow is a little long but still 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?

An output schema exists, so return values need not be explained, and the description fully covers the lifecycle: creation, replacement, validity, sharing mechanism, and the resulting friend request. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the schema carries no semantics to add. Baseline for a parameterless tool is 4; the description correctly adds no redundant parameter talk.

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 ('Make a fresh friend code') and immediately scopes it with the replacement behavior and 30-day validity. It also implicitly distinguishes the creation side from the redemption side (redeem_friend_code) by describing who creates vs. who uses the code.

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 gating condition — 'Only create one when they ask' — which prevents over-eager invocation, and describes the downstream flow that motivates sharing it. It does not, however, name an alternative tool or spell out when-not-to-use cases beyond the request condition.

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 (readOnly=false, destructive=false, idempotent=false), the description discloses rich behavioral traits: förening groups/schedule/parents' groups follow, community visibility and age-review rules, company 14-day trial with later web-only plan choice, and duplicate handling via force. This is exactly the extra context an agent needs for a complex mutation.

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 long but front-loaded with the core action, then organized by kind and exception. Every clause carries operational meaning, though the density and parentheticals make it slightly heavy.

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

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

Given the tool's complexity, the rich schema, the output schema, and the annotations, the description is complete for correct invocation. It covers all three creation paths, special review rules, trial behavior, and duplicate resolution without needing to explain return values.

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 90%, so the schema already documents most parameters. The description still adds meaningful semantics beyond the schema, such as kind-specific behavior, age/join defaults, the duplicate-force workflow, and the company trial constraint.

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: "Start a home the person will run," then enumerates the three kinds (förening, community, company). It clearly distinguishes this creation tool from siblings like list_homes or update_home, which manage existing homes.

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 a clear usage condition: "Only when they ask, with the name they chose," and a conditional exception for force when duplicates are not the person's. It does not explicitly name sibling alternatives, but no sibling create tool exists, so the practical guidance is strong.

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

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

Annotations cover only the safety profile (write, non-destructive, non-idempotent), and the description adds substantial context beyond them: the voting mechanic, 'most can' resolution the evening before, a share link for account-less friends, and the draft/send/off consent behavior. It also discloses guardrails (never invent people, prefer public places, daytime for 13–15).

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

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

Purpose and mechanism are front-loaded, and every sentence carries load (voting, share link, consent modes, safety rules). It is a dense single block that is longer than ideal, but nothing is filler.

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

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

With an output schema present, the description need not explain return values, and it covers what an agent needs to call this correctly: the recipients, the option structure, the consent gate, and the naming/safety constraints. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: the 1–9 option count, the gang-OR-friends exclusivity, and the hard rule that names must be the person's real friends/gangs. These constraints go beyond the schema field descriptions.

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

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

The description gives a specific verb+resource (propose a meetup, create a 'plan') and scopes it precisely: 1–9 time+place options to ONE gang or to friends by name/@handle. The voting/'most can' flow and share link make it clearly distinguishable from siblings like create_event or add_household_event without opening any schema.

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

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

It supplies strong when-to-use context through the consent model — 'draft' cards to Stream, 'send' creates it now, 'off' refuses — and the 'only with the person's go-ahead' precondition. It does not name explicit alternatives (e.g. create_event for one-off, non-voted events), so it stops short of a full when/when-not/alternatives treatment.

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?

Far exceeds the annotations (readOnly=false, destructive=false): it discloses the draft-by-default card, the two conditions required for immediate publishing, youth/all-ages always-draft rule, AI-made labelling, 24 h retraction window, and pre-publication photo checks. These are exactly the side effects an agent must know before writing.

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 purpose and the draft/publish consequence despite being a dense, parenthetical-heavy paragraph. Some content (publish-mode behavior) is duplicated between the description and the `mode` parameter, but almost every clause carries actionable constraints.

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

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

For an 11-parameter, multi-variant tool with an output schema already available, the description covers authoring voice, audience scoping, moderation, scheduling and reversibility. Nothing an agent needs to call this correctly appears to be missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: media ids come from upload_media, `as` is a key from list_personas/list_identities, `audience` maps to concrete channel scopes, publishAt window is 5 min–30 days, and challenge's `correct` is the right option. Only minor gaps (no explicit poll vs challenge option-count guidance beyond schema enums).

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

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

States a concrete verb+resource ("Write a post for something the person runs") and enumerates the post shapes it supports (text, media, poll, challenge) plus the persona/audience axes. An agent can distinguish it from edit_post, schedule_post and create_post_draft by the 'as/audience' framing, though the draft-default behavior does slightly overlap with create_post_draft.

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?

"Only when they ask" is an explicit usage constraint, and the description spells out the draft-vs-publish decision path and audience/identity prerequisites. It does not, however, name sibling alternatives such as create_post_draft or schedule_post, so the routing decision between near-identical tools 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?

Adds substantial context beyond the annotations: nothing is published, nobody is reached, the draft becomes a card in the person's Stream and opens Studio's composer, and imageUrl is handed back rather than fetched. This is exactly the side-effect detail an agent needs for a write tool whose annotations only say non-destructive/non-read-only.

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

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

Front-loaded with the core action and consequence, and most sentences carry real constraints. It is dense but slightly repetitive — the 1000-character cap and the 'handed back, never fetched' imageUrl behavior are each stated in both the description and the schema.

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

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

With an output schema present, return values need not be explained, and the description covers side effects, constraints, voice guidance, and the schedule_post hand-off. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents text/title/channel/imageUrl, including the 1000-character limit, the optional title, and channel-by-id/@name/name fallback. The description restates the character cap and imageUrl behavior rather than adding format or edge-case detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource (write a post draft) and its scope precisely — words plus optional title, for one of the person's channels. It cleanly separates itself from siblings like create_post (immediate publishing) and schedule_post by stating nothing is published and the draft lands in the Stream/Studio composer.

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

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

"Use it when the person asks you to draft a post" gives an explicit trigger, and it names schedule_post as the follow-up for timing. It also sets voice/accuracy constraints (write in their voice, never invent people, numbers or quotes). It stops short of explicitly routing the agent away from create_post for immediate publishing, so 4 rather than 5.

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

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

Annotations only carry the generic safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false); the description adds substantial non-obvious behavior: the object stays an unannounced draft the host must open in the app, the AI can be wrong so every question must be checked, consent gating on the AI setting, audience rules preventing adults and teens sharing a show, and content screening for teens' groups. This is real context the agent could not 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 vital information (draft-only, host review, consent gate) is front-loaded in the first sentence, which is good, but the remainder is a dense em-dash run-on packing questions, scoring, access tiers and audience rules into two oversized sentences with no structure. Some length is justified for an 11-kind nested question schema, yet the prose could be broken into scannable clauses.

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

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

For a complex 7-parameter tool with nested question objects, an output schema covering return values, and full schema descriptions, the description supplies the domain rules an agent needs — draft semantics, consent, access levels, audience separation, point cap, and the in-app-only question kinds. Nothing material to calling it correctly is left out.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still adds constraints not in the schema: 1–30 questions, the 1000-point cap per question, and the fact that picture rounds and the sound question can only be made in the app rather than supplied here. The kind list largely echoes the enum, which caps this below 5.

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

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

The first sentence states a specific verb and resource — drafting a live quiz night — plus the exact scope (a group, household chat or channel the person hosts) and the precondition that it is host-initiated. It also disambiguates from a hypothetical scheduling/announcing action by stating the result is a DRAFT nobody else sees, so no sibling tool can be confused with it.

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

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

It gives an explicit trigger ('only when they ask') and an explicit refusal condition ('refused if the person's AI setting for groups is off'), plus the constraint that nothing is scheduled until the host reviews and schedules in the app. What is missing is a named alternative sibling (e.g. list_quiz_shows for resolving 'where', or the app for picture/sound rounds) to route an agent that cannot use this tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds value beyond them: the cascade effect ('an event is cancelled for those who signed up, and they're told'), irreversibility, and the enforced confirmation workflow. This is exactly the side-effect disclosure an agent needs before a destructive call.

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: the cascade/irreversibility risk and the required confirmation are both front-loaded in parentheses and after the colon respectively, with zero 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 an output schema, full parameter coverage, and annotations covering the safety profile, the description supplies the remaining needed context: authorization scope, cascade behavior, and the mandatory confirmation protocol. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, which sets the baseline at 3. The description adds meaning to confirm by tying it to the human-confirmation step ('ask the person, then call with confirm: true'), clarifying it is a consent gate rather than a mere flag.

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 ('Delete a post') plus the scope constraint (a channel the person runs or edits), so an agent can distinguish it from edit_post or create_post without inspecting schemas.

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

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

The description gives a concrete procedural rule for invocation ('ask the person, then call with confirm: true') and constrains usage to posts the person owns or edits. It never names a sibling alternative (e.g., edit_post) for the case where deletion is not intended, 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?

Goes well beyond the annotations by disclosing that words are re-moderated, that the post receives an AI '(edited)' label unless already labeled, and the exact conditions required for direct publishing. Annotations only flag non-read-only/non-destructive; the description adds substantive operational context.

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?

Information-dense and front-loaded, with the core action and scope stated first. Sentences are somewhat run-on, but nearly every clause conveys actionable detail.

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

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

With an output schema present, return values need not be explained. The description covers authorization, moderation, labeling side-effects, and mode behavior, leaving no significant gap for an agent 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 parameters are already fully documented. The description's mode-related language largely restates the schema's own mode description rather than adding syntax or format detail, so the baseline 3 is appropriate.

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

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

States a specific verb and resource (change a post's words) and immediately delineates scope by excluding photos, time, and label as the app's domain. It is easily distinguishable from siblings like upload_media or delete_post.

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 conditional guidance: 'Only when they ask,' and explains the default card-Save path versus direct publishing with an explicit prerequisite gate. It references create_post as a behavioral twin but doesn't contrast against adjacent siblings like schedule_post for future-dated changes.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful traits beyond them: 7-day retention, 200-event cap with `more`/`next` paging, messages-preview gating on the person's Messages grant, an explicit minor (under-18) exclusion, and webhook duplication. This is unusually rich disclosure of constraints an agent must plan around.

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

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

Front-loaded with purpose, then constraints, then pagination — a sensible order. It is a single dense block and slightly overstuffed (the webhook note is tangential), but every sentence carries functional 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 an output schema present the description need not explain return shape, yet it still names the key fields and adds the operational envelope — retention window, page size, cursor loop, privacy gating. For a zero-required-parameter polling tool, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds the cross-parameter contract the schema cannot express — that `since` must be the previously returned `next`, and how `next`/`more` drive the next call. It does not add per-parameter detail for `kinds`, `limit`, or `sphere` beyond the schema.

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

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

The description states a concrete resource — the person's event stream — and enumerates the event payload (id, time, sphere, kind, line, ids, link), so an agent knows exactly what comes back. It references the sibling `context` as a companion cursor source but never explicitly says why an agent would pick `events` over `whats_new`/`read_unread`, so sibling differentiation is only partial.

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 mechanics are spelled out: pass `since` with the `next` from a prior call to advance, omit it to get the newest, and re-call with `next` while `more` is set. That gives a clear operating context, but there is no explicit when-to-use/when-not statement versus the many adjacent list/stream tools in the sibling set.

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, so the bar is lower, and the description adds real value: output varies by role (host sees counts and attendee names, viewers see only their own status and public numbers). That is behavioral detail annotations cannot express. It does not cover auth requirements or data-freshness, so not a 5.

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

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

Three sentences, front-loaded with the core answer, then role-specific detail, then the disambiguation rule. Dense but every sentence carries distinct information. The middle sentence is long but not redundant.

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

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

For a single-param read tool with full annotations and an output schema, this is complete: it explains both output modes, the absence of a 'maybe' state, and where to go for plans/meetups. An agent has 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?

There is a single parameter with 100% schema coverage, and the description adds nothing about eventId beyond what the schema (which explains the id source) already provides. Baseline 3 is appropriate; the schema does the heavy lifting.

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

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

The description opens with a concrete verb+resource ("Who's coming to a channel event") and then splits the answer by the requester's relationship to the event (host/co-host vs. viewer). It is clearly the signup/attendance status tool and cannot be confused with creation or listing siblings like create_event or list_upcoming.

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 steers the agent away from non-event cases: "Channel events have no 'maybe' — for plans and meetups use get_plan." That is a clear alternative and condition. It does not, however, differentiate from the sibling who_is_coming, which sounds like an adjacent attendee-listing tool, leaving one obvious ambiguity unaddressed.

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?

Discloses non-obvious side effects the annotations can't express: reading a conversation marks it read and surfaces in that chat's Min AI, and opening a profile reveals to its owner that the agent looked. That is exactly the context an agent needs before calling. There is mild tension with readOnlyHint=true, since marking read/notifying is a state change, but the description frames the operation as a read and the disclosure is helpful rather than contradictory.

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

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

Two sentences, front-loaded with the core action, and every clause carries information (targets, side effects, protocol). The second sentence is dense and packs several distinct ideas, but nothing is filler.

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

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

An output schema exists, so return values needn't be described, and annotations cover the safety profile; the description still supplies the side-effect and social-visibility context plus the sensitive-case protocol. Only the explicit relationship to sibling read tools is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a formatting requirement not present in the schema: appending '#told' for the profile case. That is real semantic value beyond the documented id patterns (conv:…, plan:…, hunch:…, profile:<handle>).

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

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

States a specific verb and resource ('Open one result from search by its id') and enumerates exactly what the id can resolve to: conversation messages, full plan, hunch, or whole profile. It doesn't explicitly contrast itself with the underlying siblings (read_conversation, read_profile, get_plan), so an agent still infers the relationship rather than being told it.

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?

Adds a genuine conditional protocol for the sensitive case ('tell your person first, then fetch the id with #told on the end') and notes the tool mirrors the rules of the tools behind it. It never says when to use fetch instead of read_conversation/read_profile directly, so the selection 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.

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: how a circle converts into a group chat when enough people join, and the privacy rule 'shows how many joined, never who.' It does not cover pagination or result limits, but that is minor against 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?

Front-loads what a circle is, then usage, then routing, in a compact block. The two inline examples consume space but earn it by making the abstract concept ('open circle') concrete; slightly dense, but no filler sentences.

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?

An output schema exists, so return structure is not the description's burden, yet it still volunteers the socially important 'how many joined, never who' detail. For a zero-required-parameter, read-only discovery tool with four documented params, this is nearly complete; only edge cases like empty results or radius behavior are unaddressed.

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

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

Schema coverage is 75% with self-documenting descriptions on near, activity and radius_km, plus an enum on lang. 'Search by place and/or activity' restates the schema rather than clarifying formats, defaults, or how radius_km interacts with the person's stored setting. Baseline 3 is appropriate when the schema carries most of the load.

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

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

States a concrete verb and resource ('Find open circles — public invitations') and grounds it with two realistic examples showing the shape of a result. It explicitly distinguishes itself from the sibling find_people, so an agent can pick between them 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?

Names the alternative tool and the condition that selects this one: 'Use this before find_people when the person wants to DO something with others.' That is decision-relevant routing, though there is no explicit when-not case (e.g. when the person wants one-on-one connection, use find_people) beyond the implied contrast.

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 'Open read' is redundant. The one genuinely additive behavioral detail is 'Share the pages as links,' indicating the return is shareable link pages. With annotations carrying the safety profile, this is a modest contribution.

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, front-loaded with the core definition before the usage aside. The ALL-CAPS emphasis and em-dashes are slightly noisy but the content density is high and waste-free.

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?

An output schema exists and annotations cover the safety profile, so the description need not explain returns. It adequately conveys the tool's distinctive output (complementary famous thinkers as link pages), leaving only alternative-routing guidance unaddressed.

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

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

Schema description coverage is 100% and modelId is fully documented there, including the OAuth omission rule. The description adds nothing about the parameter, 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?

States a specific verb-and-resource with a defining scope clause: finds famous thinkers who COMPLETE the person, explicitly 'not similarity.' That distinction separates it conceptually from proximity tools like find_matches and find_people, though it never names a sibling 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?

'Open read; great for curiosity and for explaining what a complementary collaborator looks like' implies exploratory usage but gives no explicit when-to-use vs alternatives (e.g., find_matches for similar people) and no when-not conditions. Usage is inferable, not 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?

Goes well beyond the annotations (which only say non-readOnly, non-destructive, non-idempotent) by disclosing that the call creates pending proposals requiring human acceptance, that identities are never revealed, and exactly what credentials are needed. That is the side-effect and privacy context an agent needs before invoking.

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

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

One dense but well front-loaded sentence opens with the verb and resource; the parenthetical rule and credential clause are load-bearing rather than filler. Slightly packed, 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 an output schema present, return values need not be explained, and the description covers auth, side effects, and the join prerequisite. Minor gap: no stated outcome for the no-match case or how pending proposals are surfaced, but the core is 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 67%, and the enum meaning for direction is already documented in the schema. The description only reinforces editToken's role as an alternative credential, leaving modelId and direction 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?

States a specific verb and resource -- find complementary PEOPLE for the connected person -- and adds the distinct mechanism (queued pending proposals). It clearly differs in kind from generic find_people, but never names the very similar sibling find_complementary_thinkers, so the agent must infer the distinction.

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 governing rule (agents propose, humans accept in the hub) and prerequisites: OAuth as owner or the model's editToken, and the target person must have joined introductions. It does not explicitly say when to prefer this over find_complementary_thinkers or find_circles.

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

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

Annotations already establish read-only/non-destructive, and the description adds genuinely new behavioral context: results are alias-only with 'never names or identities', each result carries an inspectable 'why', and contact requires the person's approval via knock. That consent model and privacy guarantee are not derivable from annotations or the input schema.

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

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

Purpose is front-loaded in the first clause, and the paragraph is dense but nearly every clause adds information (matching dimensions, return privacy, contact path). The em-dashed parentheticals and single run-on structure make it slightly heavier than needed.

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?

An output schema exists, so return-shape explanation is optional, yet the description still clarifies the alias-only/'why' nature of results, which matters for agent interpretation. The one real gap for an 8-parameter tool is sibling disambiguation among the many find_* / search_* peers.

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 moderate (63%), and the description compensates where it matters most: it defines mode semantics ('complement' = works differently in ways that help, 'similar' = alike) that the schema leaves as ambiguous as 'Default complement'. It also covers the interests/place matching dimensions, though openTo, languages and limit are left to the schema.

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

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

States a specific verb+resource (find people) and narrows it sharply: 'people who listed themselves', matched by collaboration style, interests and place. It does not, however, name or distinguish itself from the many adjacent search siblings (find_matches, find_complementary_thinkers, search_profiles), so an agent must infer which search tool applies.

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 use-case framing (new company, collaborator, friend) and an explicit next-step route: 'To make contact, use knock with a result's ref, and only with the person's approval.' No explicit when-not-to-use or sibling exclusion is stated, so the agent isn't told when find_matches would be the better 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?

Annotations only declare the safety profile (not read-only, not destructive, not idempotent). The description adds real behavioral context beyond that: flagging pauses the agent's own sending, it routes to a human, and the agent should disclose to its own principal while not confronting the other party. It does not cover reversibility, escalation timing, or auth expectations, so it stops short of a 5.

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

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

Purpose and side effect are front-loaded in the first sentence, then conditional use, then post-action behavior. The long lists are not padding — each item is a routing decision — and every sentence 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description covers when to invoke, the pausing side effect, and follow-up conduct. It is slightly silent on what the human review process does next or whether the other party is affected, which keeps it from a 5.

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

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

Schema description coverage is 50%: reason and messageIds carry inline descriptions while conversationId does not. The description's category-like list loosely maps to the enum values, but it never states how the listed scenarios correspond to a specific parameter. With half the schema documented, this is the baseline 3 — useful framing without compensating for the gap.

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

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

States a specific verb (flag) plus resource (a conversation) plus the key consequence (human review, pausing own sending). It is clearly distinguishable from adjacent siblings such as block_person, moderate_comment, or read_conversation without opening any schema.

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

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

Gives an explicit, itemized when-to-use list (threats, sexual content involving a minor, grooming, extortion, scams, self-harm, off-platform pressure, repeated contact after a no) and an explicit when-NOT-to-use list (disagreement, awkwardness, bluntness, one rude message, loneliness, difference). It also tells the agent what to do immediately after flagging. Alternative tools are not named, but the inclusion/exclusion criteria are precise enough to route correctly.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds valuable domain-specific context: the 'most can' score formula (coming=1, maybe=½), that only first names are shown, that friends who answered by link without an account are included, and that voting closes at 20:00 the evening before. It does not discuss error handling or permissions, but it meaningfully enriches behavioral understanding beyond annotations.

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

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

The description is a single front-loaded sentence that clearly states the tool's scope before listing returned details. It is dense but contains no filler, though a run-on list structure reduces readability slightly compared with a more structured presentation.

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?

An output schema exists, so the description is not strictly required to explain return values, yet it does so thoroughly. However, it omits any parameter explanation and any usage guidance relative to alternatives, which leaves gaps for an agent deciding when and how to call the tool despite the simple one-parameter interface.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It does not mention planId at all, nor explain its format or source. The single required ID parameter is somewhat self-evident from its name, but the description provides no additional 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 title and description make clear this tool reads a single meetup/plan in full, listing the specific data it returns. It is not a tautology and is distinguishable from list_plans by virtue of returning one plan completely rather than a collection. However, it does not explicitly name a verb or contrast directly with sibling list_plans.

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 no explicit when-to-use guidance, prerequisites, or alternatives. It only states what one call returns, leaving the agent to infer that it should be used when details for a specific planId are needed. No exclusions or sibling comparisons are provided.

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

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

Goes well beyond the annotations (which only say non-readonly, non-idempotent, non-destructive): it discloses board caps, opt-outs, age rules, the 50-per-round limit, privacy ('addresses are never shown to anyone else'), and the child→parent address routing. The one gap is it doesn't fully explain what 'becomes a card' does if left unsent.

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 purpose in the first clause and every subsequent clause adds substantive detail (roles, limits, privacy) rather than filler. It is dense and the Swedish jargon/parentheticals make it harder to parse, 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 nested-row tool with four roles, parent routing and privacy rules, the description covers the operational essentials, and the presence of an output schema removes any need to explain return values. The unaddressed `extra` field is the main remaining gap.

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

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

With 67% schema coverage, the description carries meaningful extra weight: it defines role semantics and the member default, explains that a child's row needs parentEmail and why, and ties groupIds to a förening's group. It leaves the `extra` param undocumented, so it doesn't fully compensate.

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: it prepares an email invite round for a home, producing a card the person taps to send. The distinction between preparing and sending is made explicit, which sets it apart from messaging siblings, but it never names a competing sibling or explains why you'd pick it over e.g. manage_member.

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 ('a home the person runs') and the home param note ('May be left out when the person runs exactly one') gives partial context. However there is no explicit when-to-use/when-not statement and no named alternative for adding people by other means.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds behavior beyond that: a conditional fallback where the caller receives a link instead of a join when the person's 'groups' setting isn't 'send', plus the side effect that hitting a threshold promotes the circle to a group chat and notifies everyone. That is meaningful side-effect and branching disclosure; auth/permission requirements remain unstated, keeping it off 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 sentences, front-loaded with the action and its gating condition, then the fallback and side effect. No filler. Slightly terse phrasing in the opening clause ('for the person') costs it the top mark.

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

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

For a one-parameter mutation tool with an output schema and annotation coverage, the description supplies what structured fields cannot: the conditional return-link path and the group-chat promotion side effect. Return-value shape is delegated to the output schema, which is acceptable, leaving only minor gaps around permissions.

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 already documented as 'circleId or slug from find_circles'. The description adds no syntax, format, or lookup guidance beyond that, so the baseline 3 for a fully documented schema 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 (join) and resource (circle), and the qualifying clause 'for the person — only when they said yes' frames the action's scope. It does not explicitly contrast with close siblings like propose_circle or find_circles, so it stops short of a 5, but the action itself is unambiguous.

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

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

Gives an explicit precondition for invocation ('only when they said yes'), which tells the agent this is a consent-gated action rather than a free-form join. No alternatives are named, so the agent must consult sibling names/parent descriptions to know when to prefer propose_circle, but the 'when' condition is real guidance.

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

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

Goes well beyond the annotations (which only say non-readOnly, non-idempotent, non-destructive) by disclosing a concrete rate limit (max 5/day), the draft-policy branch, silent declines, the approval precondition, and exactly what the recipient sees in each reveal mode.

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 purpose then packs constraints, modes, and limits into one dense paragraph with no filler. Slightly long, but each clause carries actionable 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 5-param write tool with an output schema, the description covers the decision, side effects, limits, and policy branches that an agent needs. Return values are handled by the output schema, so nothing material is missing.

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

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

Adds real meaning to the enum: identity surfaces name/handle/public links, context requires ≥40 chars and a specific content shape. message is noted as optional. shareStyle meaning is left to the schema, which already documents it, keeping this just short of 5.

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

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

States a specific verb ('knock') and resource ('someone from find_people'), and frames it as a 'first-contact request', which cleanly distinguishes it from siblings like find_people, list_knocks, and respond_knock.

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?

Clearly situates usage: the target is a ref from find_people, and it spells out the required reveal decision (identity vs context). It adds a precondition ('only with the person's approval of the wording') but does not explicitly state when to prefer this over alternatives such as other outreach tools.

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

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

Annotations already declare this a read-only, idempotent, non-destructive operation, so the safety profile is fully covered. The description adds ordering (newest first) and result content (unread counts, short preview), but an output schema exists, making that disclosure largely redundant. No pagination or limits are mentioned.

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 with zero waste, front-loading the action and resource before the ordering and payload details. Nothing could be trimmed without losing 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?

Given a parameterless read tool with an output schema and rich annotations, the description covers the essentials an agent needs. The remaining gap is scope — whether 'the person's' means the caller or an arbitrary target — and any result-count limits, which keeps it from a 5.

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

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

The tool takes zero parameters and every property is documented at 100% coverage, so there is nothing for the description to compensate for. Baseline 4 applies; no parameter semantics are needed or expected.

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 (list) and resource (conversations) plus the ordering and payload (newest first, unread counts, short preview), so it is clearly distinct from single-item readers like read_conversation. It does not explicitly position itself against ambiguous siblings such as read_unread or pro_conversations, so it stops short of a 5.

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

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

There is no when-to-use guidance, no stated prerequisites, and no mention of alternatives. The agent must infer from the name alone that this is the entry point for browsing conversations rather than reading one (read_conversation) or fetching unread items (read_unread).

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 the safety profile is largely covered. The description adds context beyond that: "Read only" as reinforcement and, more valuably, the human-in-the-loop workflow requiring the person be asked before answering, plus the confirm: true flag on the sibling.

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

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

Front-loaded with the resource and its state, and every clause contributes meaning. The "Min kanal" parenthetical and the trailing answer_follow_request workflow add length, and "Read only" duplicates the readOnlyHint annotation, so it is slightly less lean than it could be.

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

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

For a zero-parameter read tool with an output schema, the description covers purpose, state, what is returned, and the follow-up workflow. Nothing an agent needs to call it correctly is missing, and return-value explanation is unnecessary given the 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. The field-level detail (name, @username, when they asked) describes output rather than inputs, which is richer than required but not parameter semantics.

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

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

States the specific resource (people asking to follow the person's own channel, "Min kanal") and clarifies the state (waiting for their answer), plus what each entry contains. It names the sibling answer_follow_request, so an agent can distinguish the read of pending requests from the act of answering them 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?

Explicitly routes to the alternative: "To answer, ask the person, then answer_follow_request with confirm: true." This gives both the alternative tool and the prerequisite (consult the person first). It lacks an explicit negative boundary (e.g., when not to call it), so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful domain context by defining what counts as a friend, but it does not disclose ordering, pagination, or rate-limit behavior beyond the structured fields.

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

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

The description is a single concise phrase with no filler, and the core definition is front-loaded. It is appropriately sized, though it reads as a fragment rather than a complete 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 zero-parameter, read-only list operation with an output schema and rich annotations, the description supplies the one piece of domain meaning not covered elsewhere: who counts as a friend. Return values are handled by the output schema and safety by annotations, so the remaining gap is mostly usage guidance rather than missing invocation-critical information.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The empty schema and 100% schema coverage mean the baseline score of 4 is appropriate for a parameterless operation.

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 (friends) and defines it as people who exchanged a friend code, which clarifies the domain beyond the tool name. However, it does not explicitly state the list operation in the description itself and offers no sibling differentiation against alternatives like find_people or list_follow_requests.

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

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

There is no guidance about when to use this tool versus alternatives such as find_people, list_follow_requests, or pling_friend. Usage is only implied by the tool name, and no exclusions or prerequisites are mentioned.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so 'Read only' is redundant. The description earns its keep by disclosing the returned data shape and a real behavioral nuance — under-18 homes turn #kanal changes into cards requiring confirmation.

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

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

It is a single very long run-on sentence with a parenthetical aside ('then #kanal changes are cards they confirm'), which makes it dense and slightly hard to parse. The resource is front-loaded and little is truly wasted, but the structure could be broken up for clarity.

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?

An output schema exists, so return-value explanation is technically optional, yet the description still enumerates returned fields, which is helpful context. No parameters need documenting and the safety traits are covered by annotations, making this essentially 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?

This tool takes zero parameters, so per the rubric the baseline is 4. The schema is empty and 100% covered, and the description's mention of `home` refers to passing values to other tools, not to an input of this one, so no additional compensation 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 precisely (föreningar, companies, communities the person is in) and enumerates the fields returned, so an agent knows exactly what this lists. It does not, however, explicitly distinguish itself from the sibling list_households, leaving that boundary to inference.

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

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

It gives one concrete workflow rule — 'Pass a home's id or name as `home` to the other admin tools' — which clarifies downstream usage. But it never states when to call this versus list_households or the other list_* siblings, so selection guidance is only partial.

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/non-openWorld, so the safety profile is covered. The description adds genuinely non-structured context beyond that: household-specific rules govern what the person may do, and presence of an under-18 resident turns every change into a draft the person taps. That is useful behavioral disclosure not derivable from the annotations. Minor deduction for restating 'Read-only' which the annotations already carry.

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

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

One very long, em-dash-chained sentence that crams the permission list, minor-resident behavior, and today's status together. It is front-loaded with 'Start here' and wastes little, but it is dense and unstructured, and 'Read-only' duplicates the annotation rather than earning 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?

An output schema exists, so the description need not explain return values, yet it still summarizes the payload well (role, visibility, permissions, minor flag, today). For a zero-param read tool with full annotation coverage and an output schema, this is nearly complete; only sibling routing against list_homes 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?

Zero parameters, so the baseline of 4 applies — there is nothing parameter-wise the description needs to compensate for. Schema description coverage is 100% with an empty properties object, so nothing is missing.

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 (list) and resource (the person's households) and enumerates the fields returned — role, visibility, permissions, minor-in-residence flag, today's status. However, it does not distinguish itself from the sibling list_homes, nor from the field-overlapping reads (read_chores, read_dinners, read_shopping_list, read_household_calendar), so an agent cannot tell apart the entry-point summary from the targeted readers.

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?

'Start here for the household' implies this is the entry point and gives a weak sense of ordering, but there is no explicit when-to-use vs list_homes, and no when-not or exclusion guidance. Usage must be inferred from the 'start here' phrasing.

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 read-only/idempotent/non-destructive profile, and the description adds real behavioral context beyond them: the under-18 rule that everything written becomes a draft the person must publish, and the per-identity flag for whether the app may publish directly. It also discloses a scope-dependent capability (group chats/#kanaler via send_to_conversation). It does not discuss staleness, caching or rate limits, so 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?

Purpose and the critical 'call it before create_post' instruction are front-loaded, but the body is a single sprawling sentence with deeply nested parentheticals, slashes and em-dashes that make it hard to parse. Information-dense, yet it would be stronger split into a few short sentences.

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

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

For a zero-parameter, read-only listing tool with an output schema (so return format needn't be explained) and annotations covering the safety profile, the description supplies the missing why-and-when context, draft-publication rules and scope variants. Nothing essential for correct invocation is absent, though the coverage could be organized more cleanly.

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 are zero input parameters, so the baseline is 4. The description does add meaning about the returned identity record (key passed later as `as`, role, channel, offered audiences, publishability), which helps the agent map output fields to its next call, but that is output rather than parameter semantics.

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

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

The description conveys a specific resource: the identities ('as whom') a person can publish as and the audiences ('to whom') each offers, plus their key, role and publish permissions. It clearly distinguishes this from the write-side siblings (create_post, create_event, upload_media). It is clear but stated in metaphor-heavy prose rather than a plain verb+resource, 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?

Explicit when-to-use with named triggers ('when they say "post this as …" or "for the members"') and explicit precondition ('call it before create_post, create_event or upload_media'). It also names the scope-dependent extension (Messages scope → send_to_conversation) and excludes non-members ('Their own friends feed and CV are theirs alone (not here)').

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine domain context beyond that: it defines what a knock contains (identity/context, message, fit rationale) and the status taxonomy (waiting/accepted/no answer), which is valuable for an unfamiliar domain term.

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

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

A single front-loaded sentence that covers both the received and sent collections without wasted prose. The nested parentheticals make it slightly dense but every clause carries meaning.

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 zero params, complete annotations, and an output schema handling return values, the description only needs to convey scope. It does so by covering both collections and their statuses, leaving little an agent would need beyond pagination/ordering details.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% and no parameter explanation 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?

States a clear verb (list) and resource (knocks), and scopes it to both received and sent knocks with their statuses. It doesn't explicitly name a sibling to differentiate from, but it is plainly distinct from action tools like knock or respond_knock.

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

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

Usage is only implied — an agent infers this is the tool for reviewing one's knock inbox/outbox. No explicit when-to-use versus alternatives such as whats_waiting, list_follow_requests, or read_unread is given.

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/closed-world, and the description adds genuinely new behavioral context: naming is app-specific per home type (with concrete examples), admins see pending join-asks ('adults asking to lead a förening'), and a directive to keep names to the person. 'Read only' merely echoes the annotation, but the rest goes beyond structured fields.

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

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

Content is front-loaded ('Who is in a home...'), and the trailing cross-reference and 'Read only' are useful placement. The parenthetical name examples are long and the sentence is dense with em-dashes, and 'Read only' duplicates the annotation, so a small amount of trimming is possible.

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

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

With an output schema present, return values need not be explained, and the description still covers scope (whole-home vs admin-only asks), naming behavior, and the follow-on manage_member route. Nothing essential for correct invocation appears missing, though the admin-visibility distinction could be stated more explicitly.

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 `home` parameter is already well documented (name or id from list_homes, optional when one home exists). The description references the home concept but adds no format or syntax detail beyond the schema. Baseline 3 for a fully-covered schema is correct.

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

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

States the resource (who is in a home) and its scope — roles and, for admins, asks to join — which is a specific subject distinct from siblings like list_homes and list_friends. It never uses a clean verb such as 'list' and the 'a home the person is in' phrasing is a little circular, but the resource and contents are identifiable. Adequate differentiation, if not crisp.

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?

Cross-references the sibling manage_member ('Use memberId with manage_member') and notes the admin-only view of asks to join, so usage is implied by context. But it never states when to reach for this tool versus e.g. list_friends or list_identities, nor any exclusion. Guidance is present but only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is low. The description adds genuine behavioral context beyond that: it discloses that reach is measured in meetups, and that drafts live in "their Stream," which tells the agent how to interpret returned values.

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

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

Two sentences, front-loaded with the resource and followed by the routing hint. The first sentence is a dense field list, but every element is decision-relevant rather than padding; it is appropriately sized, if slightly heavy.

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

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

For a zero-parameter, read-only list tool with an output schema and full annotation coverage, this description is more than sufficient. Since the output schema already defines the return shape, describing the fields is a bonus rather than a necessity, and nothing an agent needs to invoke it correctly is missing.

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

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

There are zero parameters, so the schema carries nothing to explain and the baseline is 4. The description correctly introduces no parameter syntax, matching a no-arg list tool.

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

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

The description states a specific resource (the person's own Hunchful channels) with an explicit ownership qualifier (they are the owner, one owner today), which distinguishes it from sibling channel tools. It enumerates the returned fields (audience, live/paused, followers, reach, events ahead, scheduled posts, drafts), so an agent knows exactly what this tool yields.

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

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

"Use it first to find a channelId for the other channel tools" gives explicit routing guidance and positions this tool ahead of downstream channel tools. It stops short of naming a specific alternative or stating when this tool is NOT the right call, 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?

Annotations already carry the safety profile (readOnly, idempotent, non-destructive, closed world), so the bar is lower. The description still adds real context beyond them: the full shape of each persona entry, the cross-tool contract that the key is passed as `as` and a group name/id as `group`, and a privacy scope constraint. It does not mention ordering or pagination, but the output schema is present.

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 purpose ('What the person RUNS on Hunchful — their personas') before the em-dash enumeration. The long middle clause is dense but each item (clubs, companies, channels, classes) earns its place by bounding the resource. Minor verbosity in the stacked parentheticals.

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 zero parameters, full annotation coverage, and an output schema that documents the return shape, the description's job is mostly framing and routing - which it does well, including privacy scope. It is complete enough to call correctly; the absence of a named sibling alternative is a small gap.

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

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

The tool takes zero parameters, so the baseline is 4. The description usefully references parameters of other tools (`as`, `group`) that consume this tool's output, which is cross-tool context rather than this tool's own parameter semantics.

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

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

The description states a specific verb (list/read) and resource (personas = clubs, companies, channels, classes) and enumerates exactly what each persona record carries (key, role, channel, post permission, led groups). It explicitly distinguishes itself from neighbouring concepts by noting the friends channel and CV are 'not here', so an agent can separate it from list_friends / list_identities.

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 entry-point directive ('Start here for anything about what they run') and an explicit exclusion (friends channel and CV are not included). It also explains how the returned key feeds the `as` parameter of other tools, routing the agent downstream. It stops short of naming a specific sibling alternative for an overlapping query.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description goes further by disclosing ordering (newest first) and the returned facets (status, gang, answer-needed, leader, voting close, share link). No auth or rate-limit context, so not a 5.

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

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

Front-loaded with the subject ("The person's meetups") followed by a single em-dash enumeration and one usage sentence. It is dense but every clause earns its place, with only minor noise from the parenthetical foreign-language label.

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?

An output schema exists and annotations cover the safety profile, so the description needn't restate return structure; it still supplies ordering, field facets, and a usage cue. Adequate for a zero-param list tool, though it could note how it relates to get_plan.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify beyond what the empty schema conveys.

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 (list) and resource (the person's meetup plans they made or were invited to), with a clear scope that separates it from single-plan tools like get_plan. It does not explicitly name sibling alternatives, 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?

Provides a clear situational purpose with "Use it to nudge towards actually meeting," which tells the agent the intended context. However, it offers no exclusions or explicit routing against siblings like get_plan or vote_plan.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read only' is redundant but consistent. The genuinely additive detail is the 20-item cap; the run-down of returned fields is largely duplicated by the output schema. No contradiction, but the description stops short of discussing pagination or ordering beyond 'latest'.

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 fact (latest 20 posts on a channel you run) is front-loaded in the first clause, and the trailing field enumeration is dense but follows naturally. Slightly long and list-heavy, and the field roster partly duplicates the output schema, but there is no filler or repetition.

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

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

With an output schema present, the description needn't explain return values, and it still names the fields that matter for downstream calls. Combined with a fully described single optional parameter and read-only annotations, an agent has everything needed to call it correctly; only ordering/pagination behaviour is 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?

There is one parameter and the schema documents it at 100% coverage, including the 'key from list_identities or its name' form and the 'may be left out when only one fits' fallback. The description only gestures at it as 'a channel the person runs' and adds no syntax or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

The description names a precise verb and resource ('The latest posts ... on a channel the person runs or writes news for') and adds a hard cap (up to 20), which immediately separates it from create_post, schedule_post, delete_post and edit_post in the sibling list. An agent can tell what it retrieves and from where 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 by the parenthetical '(for edit_post, delete_post, read_comments)', which signals that this is an entry point for post-management workflows, and by the constraint that the channel must be one the person runs. However, it never states when to prefer this over neighbouring reads like list_my_channels or read_comments, nor any exclusion. Adequate but not 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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuine value beyond that: it discloses a privacy behavior (never reveals other players' names), exposes canHostIn as a permission surface, and names the downstream creation tools. It stops short of discussing pagination or freshness 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?

The core subject is front-loaded ('The person's quiz nights and daily challenges'), but the rest is a single dense run-on sentence with nested em-dash clauses that is harder to parse than it needs to be. Much of the return-field detail duplicates the existing output schema.

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

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

For a complex, relationship-heavy read tool, the description covers scope, privacy behavior, and the permission bridge to creation tools, and an output schema already documents returns. The main gap is the absence of routing guidance against the numerous sibling list 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 description coverage is 100%, so the schema already documents kind and where; the description itself never mentions either parameter and instead describes return fields (canHostIn), which belongs to the output schema. Baseline 3 applies since the schema carries 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 clearly enumerates what the tool returns (upcoming/recent quiz shows with time, questions, players, own placement; today's daily question and answer status; hosted daily-challenge state) and scopes it to groups, household chats and channels. It is specific about the resource, though the verb is implicit (it reads as a list) rather than stated, and sibling differentiation is only partial via the create_quiz_show_draft / queue_daily_challenge references.

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