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 declare readOnly/idempotent/non-destructive, so safety is covered; the description adds genuinely new behavioral context: the call-count budget, the exact return shape (body, topic_id, counters, url), and how embedding items interacts with pagination (next_offset). Only auth/permission expectations and rate limits are 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?

Extremely dense but front-loaded: the identifying statement comes first, followed by output shape, optional expansion, and routing. Every clause (call counts, next_offset, sibling pointers) carries 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 carries the burden of describing returns and does so (body, topic_id, counters, url, embedded thread_items, next_offset). It also covers the include_items toggle's cost and paging implication, 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%, so all five parameters are already documented there, including strip_html and items_body_max_chars. The description only re-ties items_limit to include_items (which the schema already states), so it adds little beyond 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 ('One discussion by numeric id or short key') and immediately distinguishes itself from siblings list_discussions and get_thread_markdown. An agent can tell it apart from list_discussions/lookup tools without opening a schema.

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

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

Explicitly routes the agent: use get_thread_markdown for prose, list_discussions for a group's threads, and this tool for a single discussion (plus the include_items variant). It also flags the cost tradeoff (1 call vs 2 with include_items) that drives the choice.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety burden is lifted. The description still adds non-obvious behavior: the response is server-rendered Markdown with `markdown`/`chars`/`truncated`, and critically that `max_chars` cuts from the END so `truncated: true` drops newest items. It does not cover auth or rate limits, but for a read tool this is well above the annotation-covered bar.

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, front-loaded with the primary use case and no filler. The packed parentheticals ('2 by discussion_id or poll_id; pass exactly one') are information-dense but slightly strain readability, keeping it just short of a 5.

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

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

With no output schema, the description compensates by naming the returned fields and the truncation flag; it also covers all four parameters, the id-selection rule, and the structured-data alternative. An agent has everything needed to call this correctly on the first attempt.

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 per-parameter meanings are already documented (baseline 3). The description nevertheless adds a cross-parameter constraint the schema cannot express — 'pass exactly one' of topic_id/discussion_id/poll_id — and reinforces the truncation semantics of max_chars, which is genuine added value.

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

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

States a specific verb and resource ('read/summarise this thread' returning server-rendered Markdown), and explicitly positions itself as 'the best single call' against the sibling list_thread_items for structured data. An agent can distinguish it from get_discussion and list_thread_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?

Explicit when-to-use ('for summarise / read this thread'), when to prefer another tool ('Structured data: list_thread_items'), the alternative ids with their cost ('+1 call'; 'prefer topic_id'), and the constraint 'pass exactly one'. Nothing about tool 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 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, but the description adds meaningful behavior: the whole thread is fetched once and sliced locally, `next_offset` signals continuation, and results are budgeted by `max_total_chars`. That pagination model is real context beyond 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?

Two dense sentences that front-load the purpose, then cover the call cost, return shape, pagination, and continuation. Slightly packed, but each clause carries information useful for correct invocation.

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 annotations and no output schema, the description supplies the return shape (`items[]` plus referenced entities), the slicing parameters, and the continuation pointer. That is sufficient 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 description coverage is 100%, so the schema already documents each of the 10 parameters in detail (including the '+1 call' cost notes). The description adds only the integrated 'pass exactly one' constraint over the id params, which is marginal beyond what the schema provides; 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?

The description names a specific verb+resource ('One thread as structured items') and clarifies the granularity (items[], not a rendered document), which distinguishes it from get_thread_markdown without naming that sibling explicitly. An agent can tell it returns structured thread data rather than a formatted report.

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 concrete routing guidance for the id parameters: use `topic_id` for 1 call vs `discussion_id`/`poll_id` for 2 calls, and 'pass exactly one'. This helps an agent pick the efficient path, though it does not explicitly state when to prefer this tool over get_thread_markdown or list_threads.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior the annotations do not: a hard 20-result cap with no paging, the `capped: true` signal, and that stance hits on hidden-result polls are dropped from a query search. That said, it stops short of naming the alternative tool for the capped case, so it is additive but not rich.

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?

Roughly four dense sentences, all front-loaded, with the two most consequential facts (20-result cap, hidden-stance drop) placed where they cannot be missed. No filler or restatement of the tool name.

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

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

No output schema exists, so the description carries the return-value burden and does so by explaining the `capped: true` marker. With all six parameters fully documented in the schema and the safety profile in annotations, nothing an agent needs to call 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 the baseline is 3. The description earns an extra point by documenting cross-parameter semantics the schema does not: how query, author_id, and their combination compose ('or both') and how the cap interacts with narrowing the search. It omits tag/types/group_id/order, which the schema already covers.

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 ('Keyword search over everything the connector's user can see') with the visibility scope made explicit. It also pins down the search modes (query, author_id, both), so an agent can distinguish it from the list_/get_ siblings without opening a schema.

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

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

Explicitly tells when to use each input ('author_id alone for what did X post', or both), and adds a hard when-not: never use search to probe hidden vote reasons. Both the selection condition and the anti-pattern are given, leaving nothing 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?

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.