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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description details the exact return values: key_status enum, the key's user, groups[] with member_state, readonly, b3_enabled, and notes[]. This adds substantial behavioral context, especially since there is no output schema.

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

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

The description is a single, densely informative sentence. It front-loads the primary usage instruction ('Call FIRST when unsure...') and then succinctly lists return fields, with no wasted words.

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

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

For a simple, no-input health probe, the description provides complete context: when to use it, what it returns, and the key statuses. With annotations covering safety and idempotency, and no output schema, nothing essential is missing 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?

The tool takes zero parameters, so the baseline is 4. The description confirms 'no input', which is consistent with the empty schema, but naturally there are no parameters to explain further.

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 ('health probe') and resource ('the connector', 'the key'), and clarifies it checks whether the connector works or what it can see. It is clearly distinguishable from all sibling tools, which deal with polls, discussions, comments, and content.

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

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

It explicitly says to call it FIRST when unsure whether the connector works or what it can see, giving clear situational guidance. However, it lacks explicit when-not-to-use guidance or mention of alternatives, though none are really needed for a unique diagnostic.

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

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

Annotations cover the safety profile (readOnly false, destructive false, openWorld true), and the description adds non-derivable operational context: call cost (1 call, 2 when discussion_id is a short key) and the server-side default that an omitted body_format is stored as Markdown. It does not warn about duplicate posts (idempotentHint=false), which is the main remaining gap.

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

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

Front-loaded with the action, then packs target rules into one dense sentence with no filler. The telegraphic shorthand ('2 when...', '+1 call') is efficient but slightly compressed relative to plain prose.

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

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

For a 5-parameter mutation tool with no output schema, the description covers purpose, both target paths, the format default, and the sibling alternative. Only the idempotency/duplicate-posting behavior and any required permissions 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?

With 80% schema coverage the baseline is 3, but the description adds value beyond the schema by mapping parent_type values to intent ('Comment' for a threaded reply; 'Poll'/'Stance'/'Outcome') and by cross-referencing the dependency between parent_id and parent_type in prose.

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

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

Opens with a specific verb+resource ('Post a comment in a thread') and immediately scopes it against siblings by naming create_discussion for new threads. The target variants (top-level vs threaded reply) further pin down what this tool does that create_poll/update_comment do not.

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 states which parameter combination selects which behavior: discussion_id for a top-level comment, parent_id + parent_type for a reply, and create_discussion for a brand-new thread. An agent can route correctly without opening any schema.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real value beyond that by listing the returned fields (id, key, url, topic_id) despite there being no output schema, and by noting the '1 call' cost and that omitting private falls back to the group default. It does not explicitly state that recipients are emailed by default (notify_recipients semantics), which the schema carries instead.

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

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

A single dense paragraph that front-loads the action, then parameters, then return values, then routing. Every clause carries information; 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?

For an 11-parameter mutation tool with no output schema, the description supplies the return fields and the required/optional split, which fills the biggest gap. It is slightly thin on the recipient-notification behavior and permissions/auth needs, but nothing essential for a correct call 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 64% and the description groups parameters into required (title, group_id) and optional, and clarifies description_format usage and the private default. However, most of that repeats defaults already in the schema, and it says only 'recipients' for the four recipient-related parameters (emails, ids, audience, message, notify flag), leaving the notification surface 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 ('Start a discussion in a group') and immediately scopes it against siblings by naming create_comment as the tool for threading and list_discussions for dedupe. An agent can distinguish this from create_poll or create_comment 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?

Explicitly tells the agent to check list_discussions for duplicates first and to use create_comment to add to an existing thread. That is a clear when-to-use precondition plus named alternatives, which is exactly what routing guidance should look like.

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 profile, but the description adds critical behaviors beyond them: call count, that omitting closing_at produces an unopened poll with opened:false and a warning, and that notify_on_open defaults to TRUE requiring explicit false for a quiet create. These are meaningful operational disclosures.

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 dense sentences front-load the creation summary and required parameters with no filler, using inline code for parameter names. Appropriately sized for a 32-parameter tool.

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

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

Given the rich schema and annotations, the description covers the critical creation-time behavioral traps (unopened draft, default announcement) and call-count implications. No output schema exists, but the description mentions key result fields, making it complete for an agent's needs.

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 94%, so baseline is 3. The description adds operational meaning for requiredness of options/closing_at and the quiet-create toggle, plus the call-count impact of discussion_id, though much of the parameter guidance duplicates existing schema 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?

States a specific verb ('Create') and resource ('poll'), distinguishes standalone vs thread call counts, and names the required fields. Sibling tools are other poll operations (get/update/delete/list), so the creation intent 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?

Provides clear context for when poll creation applies, including standalone vs inside-thread routes and the effectively-required closing_at condition. It does not explicitly name alternatives or when-not-to-use scenarios, so it falls short of full routing guidance.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds crucial nuance the annotations cannot: this is a Loomio SOFT delete, the body is blanked, the comment leaves the thread view, and the change is restorable. That materially changes how an agent should reason about irreversibility.

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

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

Three short sentences, front-loaded with the action, then the soft-delete semantics, then the alternative. No filler; each clause carries distinct 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?

No output schema, but annotations cover the safety profile and the description covers the rest: action, target, reversibility, and the sibling alternative. An agent has everything needed to call this correctly and to avoid it when updating text instead.

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 0% and there is one parameter. The description identifies `id` as a numeric comment identifier, which matches the schema's integer type and clarifies the target entity, but adds no format, range, or lookup detail beyond that. With one trivially typed param, this is adequate but not compensatory.

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 ('Discard a comment by numeric `id`') and differentiates from the sibling update_comment as well as the broader delete_* family. An agent can identify the operation without opening the schema.

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

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

Explicitly routes the agent: 'For a wording fix prefer update_comment' names the alternative and the condition that selects it. Usage is thereby bounded rather than 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 only say destructive/idempotent/not-read-only; the description goes well beyond them by disclosing that this is a SOFT delete, that the discussion leaves every list, that its text is blanked, that nothing is permanently erased, and that a group admin can restore it. That reversibility and side-effect detail is exactly what an agent needs before invoking a destructive tool.

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

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

Two tight sentences, front-loaded with the verb and target, then the soft-delete semantics, then the alternative. No filler; every clause carries operational 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 single-parameter destructive tool with no output schema, the description covers effect (blanked text, removed from lists), reversibility (admin restore), and the sibling alternative. Nothing an agent needs in order 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% and the single parameter is documented there ('Discussion id or short key'), so the schema already carries the semantics. The description references `id_or_key` but adds no format or lookup detail, 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 ('Discard') and resource ('a discussion') plus the identifier used to target it. It also distinguishes itself from a sibling ('prefer update_discussion' for text mistakes), so an agent can separate delete from update without opening 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?

Explicitly names the alternative (update_discussion) and the condition selecting it (a text mistake), which is real routing guidance. It lacks broader when-not guidance (e.g., delete vs. archive/lock, or confirm-before-delete norms), so it stops short of fully explicit when/when-not coverage.

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, so the safety profile is known. The description adds real value by qualifying that destruction: it is a SOFT delete, items leave the thread view but are recoverable by a group admin. It does not explain the response body, but the destructive-scope nuance is the important missing piece and it is supplied.

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

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

Two tightly packed sentences: the action and its soft-delete consequence come first, then the alternative routing. The '1 call' fragment is the only mildly extraneous element.

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

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

No output schema exists, and none is needed for a delete. The description covers what is removed, what is recoverable, by whom, and how to achieve the adjacent goal (closing a poll), which is everything an agent needs before invoking it.

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

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

Schema coverage is 100% and the single parameter is already documented as 'Poll id or short key.' The description only names id_or_key without adding format, accepted-key, or lookup semantics, so it does not exceed the schema baseline.

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

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

States a specific verb and resource ('Discard a poll') plus the identifying parameter, and immediately clarifies the scope of the operation. An agent can distinguish this from delete_comment, delete_discussion, and update_poll without opening the schema.

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

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

Explicitly routes the agent away from this tool for a common mis-use case: ending voting is done via update_poll with closing_at, and it notes 'no immediate close exists'. That is a concrete when-not-to-use plus the named alternative.

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

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

Annotations already cover read-only, idempotent, non-destructive, open-world, so the safety bar is met without the text. The description adds genuinely useful behavior beyond them: a call-cost model ('1 call (2+ with include_items)', '+1 call per 500 items') and the fact that next_offset signals when to page — real operational context an agent needs.

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

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

Front-loads the resource and call cost, then return shape, then opt-in embedding, then sibling routing. Extremely dense with no filler; every clause carries a fact about identity, cost, return value, or alternative.

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

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

With no output schema, the description still enumerates what comes back (full body, topic_id, counters, url) and how paging works. For a 5-param read tool with full schema coverage and annotation coverage, nothing an agent needs 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 the baseline is 3, but the description adds cross-parameter behavior the schema cannot express: include_items embeds list_thread_items output as thread_items, and items_limit interacts with the returned next_offset for paging. id_or_key and strip_html semantics are left to the schema, which fully documents 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+resource ('One discussion by numeric id or short key') and immediately notes the single-item scope vs. the batched variant. It is instantly distinguishable from list_discussions, get_thread_markdown, and the create/update/delete siblings.

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

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

Explicitly routes to two alternatives: get_thread_markdown for prose and list_discussions for a group's threads. The conditions are stated but in compressed telegraphic form ('Prose: get_thread_markdown'), leaving the agent to infer exactly when markdown beats the HTML body.

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 behavior beyond the annotations: cost (1 call), visibility rules for unjoined public groups, the exact field set returned (members_can_* included, billing subscription dropped, plus member/membership/parent/url), and error semantics (403 = hidden from user, 404 = unknown). This is exactly the destructive/edge-case context the readOnly/idempotent hints don't cover.

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 dense sentences, front-loaded with the identifier forms, then scope, then return shape, then error codes. No filler; every clause carries load-bearing 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?

With no output schema, the description fully covers the return payload and the error taxonomy, plus the non-member visibility nuance. Nothing an agent needs to call and interpret the result 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% and the description's 'numeric id, short key or URL handle' essentially restates the schema's parameter description. No additional syntax or format detail is added, 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 resource (a single group) and the accepted identifier forms (numeric id, short key, URL handle), making it clearly distinguishable from the sibling list_groups ('One group' vs a list). An agent can select it correctly 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?

Provides clear usage context that it 'works for public groups the user has not joined,' which tells the agent this is usable even without membership. It does not explicitly name list_groups as the alternative for multiple groups, 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 cover safety (readOnly, idempotent, non-destructive), so the description adds genuinely useful behavior beyond them: anonymous polls excluded, zero-activity users dropped unless include_inactive, and the non-obvious counting rule that a vote counts in the month its counted stance row was created. These are real disclosure wins for a reporting tool.

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

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

Two dense sentences pack the ranking behavior, scoping options, and counting caveat up front with essentially no filler. The semicolon-chained clauses are information-dense rather than wasteful, though slightly cramped.

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

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

No output schema exists, so the description carries return-shape burden: it tells the agent it gets one row per user with a `total` value sorted descending, which is the key information. Full column set is not enumerated, but for a 7-param report this is close to sufficient.

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

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

Schema coverage is 100%, so the schema already documents all 7 parameters including ranges and defaults. The description largely restates them ('default 50, max 500', group_ids 1-50) and only marginally adds the 'counted together' relationship, so baseline 3 is warranted.

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

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

States a specific verb+resource ('rank the members of a group set') and clarifies it returns Loomio's own report, one row per user sorted by `total` desc. It is unambiguous, though it does not explicitly name a sibling such as get_user_activity to differentiate the two activity-style tools.

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

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

Explains how to scope the report ('group_ids' counted together or 'group_scope: my'), which implies usage, but never states when to choose this tool over alternatives like get_user_activity or get_group. Inclusion rules (include_inactive, zero-activity dropped) give some operational guidance but no true when-to-use framing.

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/openWorld/idempotent/non-destructive), and the description adds behavior annotations cannot: the results-gating fields and the critical gotcha that 'absent counts mean HIDDEN, never zero.' This is exactly the kind of disclosure that prevents misinterpretation.

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 return shape, then sibling routing, then the gating caveat — dense and waste-free. The return-field enumeration is verbose but earned given the absence of an 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?

With no output schema, the description carries the return-value burden and does so fully: it names the key fields, the gating fields, and how to fetch votes. Nothing an agent needs to call and interpret this tool 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 are already documented ('Poll id or short key', 'Plain text instead of HTML; default false'). The description restates the id/key duality but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('One poll') and its lookup modes ('by numeric id or short key'), immediately distinguishing it from list_polls, create_poll, and update_poll. An agent knows exactly what it retrieves 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?

Clear context for single-item retrieval and a concrete routing hint for related data ('votes as items: list_thread_items with its topic_id'), which steers the agent to the right sibling for votes. However, it never explicitly contrasts itself with list_polls or states exclusions.

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

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

Beyond annotations (readOnly/idempotent/openWorld), it discloses the call-cost multiplier, a hard refusal condition tied to poll result hiding, and precise truncation semantics — max_chars cuts the END and `truncated: true` means the newest items were dropped. That is real operational context an agent cannot get from the 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?

Front-loaded with the primary use case and tightly written with no filler. It is telegraphic to the point of density (backticked fragments, parentheticals), which slightly taxes first-read comprehension, but nothing is wasted.

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

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

With no output schema, the description still names the return fields (`markdown`, `chars`, `truncated`), covers the failure mode, and explains the truncation contract. 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 coverage is 100%, so baseline is 3; the description adds the crucial exclusivity rule ('pass exactly one') that the schema's flat property list does not enforce, plus the cost impact of thread size. The max_chars explanation largely restates the schema text, keeping it below a 5.

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

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

States a specific verb and resource ('read/summarise this thread') and names exactly what it returns: Loomio server-rendered Markdown plus `markdown`, `chars`, `truncated`. It also distinguishes itself from the sibling `list_thread_items`, so an agent can choose 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?

Explicit routing rules: 'pass exactly one' of topic_id/discussion_id/poll_id, and an explicit when-not case — REFUSED while an open poll hides results, use list_thread_items instead. It also gives the cost model (2 calls, +1 per 500 items) which informs the use/don't-use decision.

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

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

Annotations already declare this as a safe idempotent read, so the bar is lower, yet the description adds substantial domain behavior: month-graining that widens since/until to whole months, the rule that anonymous polls never count, and the stance-row month attribution rule for votes. It also discloses that sample_events are newest items with urls, not a full list.

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 required params, then return shape, then the MONTH-GRAINED rules; every clause carries information. It is dense and heavy on terse fragments, 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 four-parameter read tool with no output schema, the description covers the return fields (counts, by_group, sample_events), the date-windowing semantics, the counting rules, and where inputs are sourced. 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 100%, so the baseline is 3, but the description adds meaning beyond the schema by specifying the source of user_id (list_memberships or a participation row) and the month-widening consequence of since/until. The '1 call each' note on group_ids largely restates 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: retrieving one person's participation across groups. The '1 call per group + 1' batching detail is distinctive and helps an agent understand the call pattern. It implies but does not explicitly name the contrast with get_participation_report, so it stops short of full sibling differentiation.

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

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

It tells the agent where required values come from (user_id from list_memberships or a participation row), which is useful workflow guidance. However, it never says when to prefer this per-user view over the sibling get_participation_report, nor states any exclusions, leaving the when-to-use decision 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 cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is clear. The description adds behavioral details: default status filtering, pagination hints via '1 call', and default strip_html. However, return format and pagination behavior are only partially addressed. Baseline 3 appropriate given annotations carry the core traits.

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?

Efficient and front-loaded: the primary purpose and scoping are stated first, followed by parameter defaults and related tools. No wasted words. Could be tightened further but is well structured.

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 list tool with annotations covering safety and schema covering most parameters, the description provides useful defaults and scoping. However, it does not mention pagination behavior (offset/limit interaction) or return structure, and there is no output schema. Adequate but incomplete for an agent needing to call 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 83%, so most parameters are already described. The description adds behavioral nuance for status default, description_max_chars truncation behavior (with description_truncated flag), and strip_html default, which goes beyond schema. This is slightly above baseline but not rich enough for a 4.

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 ('One group's discussions') and a scope constraint (subgroups excluded). Does not explicitly name the related sibling get_discussion or list_threads, though it does reference list_threads in a different context. Distinguishable from siblings but not maximally so.

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 alternatives: 'Every visible group: list_threads' and 'keywords: search_content', giving clear when-to-use context for related tasks. Lacks explicit when-not or differentiation from get_discussion / list_polls. Adequate but not comprehensive.

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/openWorld, so safety is covered. The description adds return-shape behavior not in structured fields: pending invitations are included and subgroup parents are emitted with `member: false`. It does not discuss auth requirements or pagination, but adds genuine value beyond annotations.

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

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

Three tight clauses, output scope front-loaded, then the call cost, then the sibling contrast. No filler anywhere.

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

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

No output schema exists, so the description carries the return-value burden, and it does explain two notable return behaviors. Pagination and ordering are unaddressed, which is a minor remaining gap for a list tool.

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

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

Zero parameters, so the baseline is 4; the description confirms 'no input', which matches the empty schema. Nothing further 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 specific resource (the connector user's groups) with scope detail (pending invitations included) and explicitly distinguishes itself from the sibling get_group, which 'reads one record'. An agent can pick between list_groups and get_group 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?

The contrast with get_group ('get_group reads one record, even a public group this list omits') gives clear routing guidance for the list-vs-single-record choice. It does not spell out broader when-not-to-use cases, but the key sibling decision is covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral nuance beyond them: user_email is only populated when the caller is a group admin, and a non-member receives an empty list rather than 403 — plus an explicit instruction not to misreport that as an empty group. This is exactly the kind of context annotations cannot convey.

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

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

Dense but front-loaded: scope, return shape, then usage rules, then the empty-list caveat. Nearly every clause earns its place, though the return-shape enumeration is tightly packed and slightly cluttered with backticks.

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

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

With no output schema, the description compensates by naming the returned keys (memberships[], users[], total) and the admin-conditional field, plus the critical empty-list edge case. An agent has everything needed to call and interpret this 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%, and the schema already documents limit, offset, and the group_id non-member/empty-list behavior. The description's group_id remark largely restates the schema, adding no new syntax or format detail. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific resource and scope ('A group's members: 1 call') with a clear read verb implied by 'list_memberships'. It is distinguishable from list_groups/get_group, though the differentiation from manage_memberships comes through the usage note rather than the purpose statement itself.

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 states two use cases: resolving a name to a user_id, and the mandatory pre-step before manage_memberships with remove_absent. Names the sibling tool and the exact condition that requires this call first.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real behavioral detail beyond them: newest-first ordering, slim rows, conditional presence of poll_options[] and stance_counts gated by results_visible, and the effect of strip_html on details. It still doesn't state pagination behavior or total counts, 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?

Dense and front-loaded, with the scope/ordering statement first and the routing caveat last. The telegraphic fragment style ('1 call', semicolon-joined clauses) is efficient but slightly cryptic and costs a point on readability.

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

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

With no output schema, the description compensates by describing the row shape (poll_options[], stance_counts, results_visible) and the `details` field. Combined with schema-documented paging and defaults, 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 83%, so the baseline is 3. The description adds semantic links the schema doesn't make on its own: that description_max_chars caps `details` specifically, and that strip_html controls whether details come back as HTML.

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

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

States a specific verb and resource with scope and ordering: 'One group's polls, newest first: 1 call.' It is immediately distinguishable from siblings like get_poll (single poll), create_poll, and list_groups.

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 away from a tempting wrong path: 'For member activity use get_participation_report, not this plus list_memberships.' That is a clear when-not plus a named alternative, though it covers only this one scenario and says nothing about paging or when to prefer get_poll.

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?

Even with annotations covering readOnly/idempotent safety, the description adds real behavioral context: the extra API call cost per 500 items for topic_id versus +1 for discussion/poll id, the `max_total_chars` reply budget, and default `strip_html` behavior. It doesn't disclose error behavior when multiple ids are passed, so it stops short of 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 core purpose and return shape, then pagination. Dense with parenthetical clauses, but each earns its place; only the stacking of several asides makes it slightly harder to scan than ideal.

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

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

For a 10-parameter read tool with no output schema, the description covers return shape, ordering, paging semantics, and budget behavior. Gaps remain around item ordering guarantees and multi-id error handling, but nothing critical is missing for a correct call.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by stating the otherwise-invisible constraint that exactly one id must be passed (schema marks zero required), plus the call-cost differential and the note that `kinds` ignores paging. This adds genuine meaning beyond the schema.

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

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

States a specific verb+resource: returns 'one thread as structured items,' distinguishing it implicitly from the markdown-oriented sibling by emphasizing structured `items[]` plus referenced comments/polls/stances/users. It does not explicitly name an alternative sibling, which keeps it from a 5.

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

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

Gives a concrete selection rule for the three id parameters ('pass exactly one', 'prefer topic_id') and explains pagination continuation via `next_offset`. It lacks explicit when-not guidance against siblings like get_thread_markdown or search_content, so not 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral context: no bodies returned, `group_id`/`type` filtering happens client-side within the page, and `total` stays instance-wide. What it does not fully disclose is what `scope.exhausted` actually contains or how many pages a typical traversal needs.

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

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

Front-loaded with the value proposition and return shape, then the caveats; no filler sentences. The parenthetical stacking makes it dense and slightly hard to parse, but nothing is padding.

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

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

With no output schema, the description carries the return-value burden and does so by listing the key fields and noting the absence of bodies. Combined with the paging loop and client-side filter caveats, an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining that `group_id`/`type` are client-side filters and that `since`/`offset` drive a page-until-exhausted loop. This adds operational meaning (especially that `total` is not scoped to the filter) beyond the per-parameter schema text.

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 ('lists every visible thread, newest activity first') and enumerates the returned fields, so the agent knows exactly what comes back. It also distinguishes itself from the single-group siblings by naming list_discussions / list_polls as the narrower alternatives.

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?

Positions the tool as 'the cheapest what-is-new across everything I can see' and explicitly routes single-group lookups to list_discussions / list_polls. It even prescribes the paging pattern (pass `since`, page with `offset` until `scope.exhausted`), so when and how to use it is unambiguous.

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

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

Goes well beyond annotations (which only flag destructive=true, idempotent=false): it names the admin-of-that-group auth requirement, the self-removal hazard ('own user included'), and the irreversibility ('no undo'). This is exactly the safety context an agent needs before a destructive 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?

Front-loaded with the core action and default, then the danger. It is dense but each clause earns its place; the '1 call' phrase is slightly superfluous but minor.

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

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

For a 3-param destructive mutation with no output schema, the description covers auth requirements, default vs destructive semantics, self-inclusion, irreversibility, and a recommended pre-check workflow. Nothing an agent needs to invoke it safely 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%, and the schema already documents emails ('ensure are members'), group_id (admin requirement), and remove_absent (dangerous/default false). The description largely restates that, so it earns the baseline 3 rather than adding new 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?

States specific verbs (invite, remove) and resource (group memberships by email), and explicitly contrasts the additive default against the destructive remove mode. An agent can distinguish it from list_memberships 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 tells the agent that the default is additive ('nobody is touched') and that remove_absent:true triggers destructive removal, then prescribes a workflow: call list_memberships first and confirm the diff with a human. When-to-use and when-to-be-careful are both stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds genuinely new behavior beyond that: a hard cap of 20 results with no paging, the meaning of `capped: true`, and that stance hits on polls with hidden results are DROPPED from query searches. That is real added value, though the return shape of individual results is left unstated.

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

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

Dense and front-loaded: scope, then parameter modes, then the cap, then the exclusion caveat. Each sentence carries information, though the phrasing is telegraphic enough that some clauses (e.g. 'Stance hits on polls with hidden results are DROPPED') require a second read.

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

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

There is no output schema, so the description reasonably must mention return behavior — it covers the 20-result cap and the `capped` flag, but does not describe what a result item looks like or how `relevance` ordering interacts with the cap. For a six-parameter search tool with full schema coverage, this is close to sufficient.

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 per-parameter baseline is 3, but the description adds combination semantics the schema does not: `author_id` alone yields that author's 20 newest items, and query+author_id compose. It also reinforces the prefix-match and `!word` exclusion syntax and ties the result cap to the `capped` 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 (keyword search) and resource scope ('everything the connector's user can see'), and explicitly contrasts with the enumerate-style siblings by noting it is a single call reaching all record types. An agent can immediately tell this apart from list_discussions/list_polls/get_* tools.

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

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

Gives concrete invocation modes: pass `query`, pass `author_id` alone for 'what did X post', or both. It also states an explicit prohibition ('never use search to probe hidden vote reasons'), which is the kind of when-not guidance most descriptions omit.

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 the body REPLACES the entire text (matching destructiveHint=true), the authorization model, and the thread-lock constraint. Annotations flag safety profile; the description fills in the operational consequences an agent needs.

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

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

Front-loaded with the verb and '1 call', then packs replace-semantics, params, and auth into one dense passage. Slightly redundant with schema wording on the body-replacement rule, but no wasted 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 mutation tool with no output schema, it covers auth requirements, destructive replace behavior, and prerequisites adequately. Return-value expectations are left implicit, which is acceptable given the tool's simple edit semantics.

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

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

Schema coverage is 67% and the body/body_format descriptions already appear in the schema, so the description largely repeats structured data ('REPLACES the whole text', 'html' example). It adds identification of the undocumented id as 'numeric' and required, but little else beyond the baseline.

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

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

States a specific verb+resource ('Edit a comment') and immediately disambiguates it against the create/delete_comment siblings by describing an in-place edit that REPLACES the whole body. An agent can select it confidently 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?

Provides clear preconditions: author/thread-admin permission, thread must be unlocked, and routes the agent to list_thread_items to read the text before replacing it. No explicit 'use X instead' exclusion, but the context is concrete and actionable.

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 and idempotentHint, but the description adds critical specifics beyond them: description fully REPLACES the body (forcing a read-first, send-whole-text workflow), threads cannot be moved, tags cannot be changed, and discarded threads cannot be edited. These negative constraints are exactly the context an agent needs before mutating.

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, well-ordered sentence: identification, partial-update rule, the destructive replacement warning, then the impossibility constraints. No filler, and the highest-risk behavior (body replacement) is front-loaded.

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

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

For a 13-parameter mutation tool with no output schema and strong annotation coverage, the description covers the essential behavioral traps. Minor gaps remain around recipient/notify effects and permission requirements, but the core editing contract 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 92%, so the schema carries most parameter meaning. The description still adds value by grouping the changeable fields ('allow_* flags, recipients to add') and emphasizing the replace-not-merge semantics of description, which the schema only states tersely.

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 ('Edit a discussion by id_or_key'), identifies the key parameter, and scopes it as a single call. An agent can distinguish this from create_discussion or update_comment 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?

'Pass only what changes' plus the 'read it first' workflow for description give clear operational context, and the closing sentence lists what the tool cannot do. It stops short of naming a sibling alternative (e.g. update_comment) the way a 5 would, but the usage context is unambiguous.

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

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

Goes well beyond the annotations: discloses that details REPLACES existing text, options are ADD-only and merged (never removes), the merge is not atomic, opening a draft announces a poll, and a closed poll returns 403. These are exactly the destructive/stateful traits an agent needs and the annotations alone (destructiveHint, idempotentHint) do not convey.

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

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

A single dense paragraph that is front-loaded with the action and the call-count note, then lists the mutability contract and exclusions. Every sentence carries information; only the count of packed clauses keeps it from being maximally clean.

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 27-parameter tool with high schema coverage, a safety profile in annotations, and no output schema, the description supplies the missing behavioral context (overwrite, merge, non-atomicity, 403, announce-on-open). Return values needn't be described since no output schema exists.

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 93% schema coverage the baseline is 3, but the description adds real semantic value: 'Pass only what changes', details overwrite behavior, option merge semantics, and future-only closing_at. It clarifies the update-patch contract that the schema type constraints alone don't express.

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 (Edit) and resource (an OPEN poll) with the identifying parameter (id_or_key), and the constraint that it must be open immediately differentiates it from create_poll/delete_poll siblings. An agent can identify the operation without opening the schema.

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

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

Gives clear when-to-use conditions (only open polls; closed returns 403) and explicit when-not boundaries (cannot change poll_type, anonymous, group, tags). It doesn't name a sibling alternative by name, but the create/delete/update triad is unambiguous from context.

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