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

Annotations show readOnlyHint=false (write operation), destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds behavioral context beyond annotations: it states permission requirement ('Caller must be permitted to post in the discussion's group'), and default behavior for body_format. It does not mention return value or side effects, but with openWorldHint=true, this is acceptable. Slightly incomplete but adds meaningful value.

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

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

Four sentences, front-loaded with purpose, then parameter info, then usage guidance, then alternative. Every sentence provides necessary information without redundancy. Extremely concise and 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?

Given the tool's simplicity (3 params, no output schema), the description covers purpose, usage, permissions, parameter details, and alternative tool. It addresses all essential aspects for an agent to select and invoke this tool correctly. Missing return value is acceptable since no output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description rephrases the required and optional parameters ('Required: discussion_id, body. Optional body_format') and adds default behavior ('defaults to the group's setting'), which is already in the schema description. No new semantic information beyond schema.

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

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

The description clearly states 'Post a comment (reply) on an existing Loomio discussion.' It uses a specific verb (post), resource (comment/reply), and scope (existing discussion). It explicitly distinguishes from the sibling tool create_discussion by stating 'For starting a new thread instead, use create_discussion.'

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

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

The description provides explicit when-to-use scenarios: 'reply to thread X', 'add a follow-up to discussion Y', or 'chain a series of automated updates.' It also specifies a when-not-to-use alternative: 'For starting a new thread instead, use create_discussion.' It mentions required and optional parameters, and permission requirements.

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 are minimal (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds substantial behavioral context: it explains the create action, the required parameters, the special handling for private discussions, and the error scenario. No contradictions with annotations.

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

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

The description is front-loaded with the purpose and key requirements, then covers optional parameters and limitations. It is fairly long but every sentence adds value; no wasted words. Could be slightly trimmed but overall well-organized.

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 18 parameters, 78% schema coverage, no output schema, the description is comprehensive. It covers creation, parameter dependencies, and a known edge case. It does not explain the response structure, but that is acceptable since the tool creates a resource and the output is likely the poll object. The description is complete for the agent to use 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 78%, so many parameters already have descriptions. However, the description adds meaning beyond schema: it explains the poll_type enum values, the requirement for options for most types, the group_id vs discussion_id decision, and the crucial known limitation. This enriches the semantics.

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

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

The description clearly states 'Create a new Loomio poll' with specific verb and resource. It distinguishes from sibling tools (create_comment, create_discussion) by focusing solely on polls and detailing required fields like title, poll_type, and the different types.

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

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

The description provides explicit when-to-use guidance: it explains that for poll types other than 'proposal', options MUST be supplied, and the choice between group_id (standalone) and discussion_id (attached to thread). It also warns about a known upstream limitation and suggests a workaround, effectively telling when not to use (groups requiring public discussions).

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

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

Annotations already mark the tool as read-only and idempotent. The description adds rich behavioral context: the fan-out mechanism, cost model (~1 HTTP call per discussion), concurrency cap, parsing of scope.complete fields for partial results, and warnings about lower bounds when data is incomplete. No contradictions with annotations.

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

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

The description is long but well-structured with front-loaded purpose, clear sections (server-side steps, usage guidance, cost, completeness handling). Every sentence adds value, though some redundancy exists. The structure compensates for length, making it easy for an AI agent to parse.

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?

Despite no output schema, the description thoroughly explains what is returned (counts by kind/group/month, timestamps, sample events, scope.complete field). It covers partial result handling, error scenarios (groups_failed, etc.), and how to interpret incomplete data. This is complete for the tool's complexity.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaning beyond schema: explains why group_ids should come from list_groups, constraints on since/until (ISO-8601, ordering), and the practical cost implication of group_ids argument. This enriches parameter understanding beyond the schema.

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

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

The description starts with a specific verb+resource ('Aggregate one user's activity across a set of groups'), clearly distinguishes from siblings by explicitly naming alternatives (list_events for single discussions, list_groups for scoping), and provides concrete examples of when to use. The purpose is unambiguous and well-differentiated.

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

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

Explicitly states when to use ('USE THIS for any user-centric question'), when to not use (single discussion → list_events; checking group visibility → list_groups), and gives detailed usage patterns for multi-user comparisons. Alternatives and exclusions are fully enumerated.

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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds behavioral context: 'Caller must be a group member,' pagination with `limit` and `offset`, and ordering by latest activity. No contradictions.

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?

Description is a single paragraph but well-structured: starts with main action, then required param, optional params with defaults, use cases, and sibling reference. Every sentence adds value; 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 list tool with no output schema, description covers purpose, required/optional parameters with defaults, member requirement, pagination, and use cases. Lacks output description but ordering is noted. Sufficient for selection and invocation.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds meaning: clarifies `group_id` is required, explains `status` enum values (open/unlocked, closed/locked, all), notes default `limit` is 50, and describes `offset` for pagination. This goes beyond 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?

Description clearly states 'List discussions in a Loomio group, ordered by latest activity,' specifying verb, resource, and ordering. It distinguishes from sibling tool `get_discussion` by noting 'For one specific thread, use get_discussion.'

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 explicit use cases: 'to answer what's being discussed in group X, show me recent threads, or before create_discussion to check for duplicates.' Mentions alternative `get_discussion` for single threads. Lacks explicit when-not-to-use, but guidance is clear.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds context on the workaround mechanism, 404/403 handling, scope, and slimmed return fields, providing incremental behavioral transparency without contradiction.

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

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

The description is detailed but well-structured, front-loading the purpose. Every sentence adds value, though it could be slightly trimmed without losing clarity.

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

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

Given the lack of output schema, the description adequately explains return fields, cost, and limitations. It covers all necessary context for an agent to use the tool 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% with descriptions. The description further clarifies defaults, the 500-id limit, and the early-exit heuristic, adding significant 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?

The description clearly states the tool lists groups visible to the API key user via a probing workaround, distinguishes from other tools by explaining the lack of a native endpoint, and specifies the return scope (member groups, admin bypass).

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 this is the right tool for 'what groups can you see' discovery, identifies alternatives for drill-down (list_memberships, etc.), and warns about the cost (~50–200 HTTP requests).

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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds critical context: caller must be admin (non-admins get 403), response includes email only for admins, and names/ids are still reachable via other tools. This goes beyond annotations without contradiction.

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

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

The description is front-loaded with the core purpose and each sentence adds value. While slightly long, it is well-structured with clear sections. Minor redundancy (e.g., re-explaining parameters) keeps it from 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?

Given the tool's complexity (3 params, no output schema, but strong annotations), the description is thorough. It covers purpose, parameters, usage guidelines, behavioral details, and alternatives. Lack of explicit return format is acceptable since annotations and schema cover most 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 coverage is 100%, so baseline is 3. The description adds value by clarifying group_id is required with admin requirement, limit range 1-200 default 50, and offset defaults to 0. It explains behavior beyond schema, justifying 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?

The description clearly states the tool lists Loomio group members with email, roles, and join state. It specifies the required parameter group_id and differentiates from siblings like manage_memberships, list_polls, and get_user_activity, providing a specific verb+resource with sibling distinction.

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

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

The description explicitly states when to use (e.g., answer 'who's in group X', before calling manage_memberships) and when NOT to use (e.g., avoid constructing participation analysis; use get_user_activity instead). It provides clear context and alternatives, fulfilling the highest standard.

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 indicate readOnly, non-destructive, idempotent, and open-world. Description adds that caller must be a group member, explains default filter behavior, ordering, and pagination parameters. Also details the ambiguity between 'didn't vote' and 'abstained' that list_polls cannot resolve, which is valuable behavioral context beyond annotations.

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

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

The description is well-structured: first sentence defines purpose, then details parameters, then use cases, then sibling differentiation. It is relatively concise but contains some redundancy (e.g., 'Caller must be a group member' could be part of parameter notes). Still, no filler sentences.

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

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

Given no output schema, the description explains ordering, pagination, membership requirement, and use cases. It covers the main aspects needed to use the tool correctly. Could mention what fields are returned per poll object, but overall sufficient for a simple list tool with good annotations.

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%; description reinforces defaults and meanings (status default 'active', limit default 50, offset default 0). Adds clarity on the 'all' status option ('every kept poll') and explains that status defaults to 'active'. This provides additional context not in 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?

The description clearly states 'List polls in a Loomio group, ordered by creation date (newest first).' It specifies the action (list), resource (polls), and scope (group with ordering). It also distinguishes from sibling 'get_user_activity' by noting it for per-user participation questions.

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 explicit required parameter (group_id), optional filters with defaults, and concrete use cases: 'what's up for vote in group X', 'show me past poll results', 'check what's already proposed'. Also clearly states when not to use it: for per-user participation questions, prefer get_user_activity, with reasoning about ambiguity.

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

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

Discloses destructive nature, no dry-run, no undo, and the risk of wiping the group. Adds significant context beyond annotations that already mark it destructive.

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?

Every sentence adds value, front-loaded with purpose and danger warning. Length is justified by complexity of the 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?

Covers required params, optional danger flag, preconditions, side effects, and return value. Complete for a tool with no output schema.

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

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

Schema coverage is 100%, but description adds crucial context: explanation of additive mode, danger of remove_absent, and admin requirement. Exceeds the baseline 3 for fully covered schemas.

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

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

The description clearly states it invites users by email and optionally removes absent members. It distinguishes from siblings like list_memberships and other group-related 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?

Explicitly guides on when to use default additive mode vs. dangerous remove_absent option. Recommends calling list_memberships first and confirming with a human, setting clear usage boundaries.

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