mcp-server

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

Annotations indicate mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds critical behavioral details: recovery codes returned once, storage importance, key recovery does not clear 2FA. Exceeds annotation coverage.

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

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

Concise, front-loaded with core action, includes essential warnings and error info. No extraneous text. Efficiently 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 3 required parameters, annotations, and output schema, description covers activation flow, one-time codes, and errors. Could mention rate limits or retry behavior, but not required. Adequate for use.

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. Description adds flow context by tying secret/ticket to enrollment and code generation, which helps understand usage. No additional parameter-level details 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?

Clearly states 'Activate TOTP 2FA' with verb and resource, and explains the flow using secret, ticket, and code. Distinguishes from sibling tools like colony_2fa_enroll and colony_2fa_disable.

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

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

Explicitly says to use output from colony_2fa_enroll and warns about one-time recovery codes. Provides error examples. Does not explicitly exclude other uses, but context is clear.

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

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

The description aligns with annotations (destructiveHint=true), mentions required code and error types, and explains the effect (turning off 2FA). However, it does not elaborate on consequences like reduced account security, which would enrich transparency.

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 very concise: two sentences, no unnecessary words. The first sentence states the purpose, the second provides requirements and potential errors. Perfectly front-loaded and efficient.

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

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

Given the tool's simplicity (one required parameter, clear destructive action) and the presence of output schema, the description is largely complete. It covers purpose, requirements, and errors. A minor omission is not mentioning that disabling 2FA reduces security, but overall it's 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?

The input schema already fully describes the 'code' parameter with constraints and meaning (100% coverage). The description adds minimal extra value beyond repeating the requirement, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Turn OFF your TOTP 2FA', using a specific verb and resource. It effectively distinguishes itself from sibling tools like colony_2fa_enroll and colony_2fa_confirm.

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 lists requirements (valid code) and errors, but does not explicitly state when not to use this tool or suggest alternatives (e.g., 'use colony_2fa_enroll to enable 2FA'). The context implies usage but lacks explicit exclusion 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 are sparse (all false hints), so the description carries the burden. It explicitly states 'NOTHING is persisted yet', revealing that the operation is non-destructive and only returns data. It also documents the expected error, which is valuable for the agent. The description adds necessary 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?

The description is a single concise paragraph, well-structured: it states the action, lists return values, clarifies what does NOT happen, provides workflow steps, and mentions an error. Every sentence adds value, with no filler.

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

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

For a zero-parameter tool, the description is complete: it explains the return values, the next required step, and an error condition. The existence of an output schema is noted, but the description already covers the key outputs. No gaps remain.

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 has no parameters, and the schema coverage is 100%. The description does not need to explain parameters. Baseline for 0 parameters is 4, and no additional param info is needed.

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

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

The description clearly states the purpose: begin TOTP enrolment. It specifies the output (secret, otpauth_uri, ticket) and contrasts with colony_2fa_confirm, making it easy to distinguish among siblings.

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

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

The description explains the workflow: nothing is persisted yet, feed the secret to a TOTP library, then call colony_2fa_confirm with secret, ticket, and code. It also mentions the AUTH_2FA_ALREADY_ENABLED error, implying when not to use (if already enrolled). However, it does not explicitly suggest checking status first via colony_2fa_status, so it misses a clearer exclusion.

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

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

Beyond the destructiveHint annotation, the description discloses that new codes are returned only once and old ones are invalidated, and specifies exact error codes. This adds valuable behavioral context.

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

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

Two concise sentences with no wasted words. Front-loaded with the core action, followed by prerequisite and errors. Efficient 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?

For a simple tool with one parameter and an output schema, the description covers purpose, prerequisite, behavioral details, and errors. No gaps remain for an agent to use 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 schema already covers the code parameter with length constraints, but the description adds meaning by specifying acceptable formats (TOTP vs recovery code) and that it must be current, which aids correct invocation.

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 replaces recovery codes with a fresh set, invalidating the old ones. This verb+resource+scope is specific and distinguishes it from sibling tools like colony_2fa_confirm, disable, enroll, and status.

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 indicates prerequisite (requires valid current TOTP or recovery code) and lists error conditions, providing clear context. It doesn't explicitly state when not to use or name alternatives, but the purpose is clear enough among siblings.

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

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

Annotations already declare readOnly and idempotent; description adds value by specifying the exact return format including field names and types.

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 concise sentences, first states purpose, second gives output format, no fluff.

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 parameters and output schema implied by the description, the tool is fully specified for a simple status check.

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?

No parameters, so schema coverage is 100%; description adds nothing about parameters, but baseline for zero params is 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?

Description clearly states the tool checks if TOTP 2FA is enabled and returns recovery codes count, distinguishing it from siblings like colony_2fa_enroll and colony_2fa_disable.

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

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

Usage is implied by the name and purpose, but no explicit when-to-use vs alternatives, though siblings make it clear this is for status checks.

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 write operation. Description adds context: requires mod authority, writes to ModLog. No contradiction 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?

Two sentences, no redundancy. Front-loaded with action and resource. Efficiently conveys essential 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?

Simple operation with three parameters described well. Output schema exists. Description sufficiently covers behavior and constraints.

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 descriptions cover 100% of parameters. Description adds marginal value: clarifies note is mod-private and unseen by member. 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?

Clearly states the action 'Add a mod-private note' and the resource 'colony member's running log'. Distinguishes from sibling tools like colony_delete_member_note and colony_list_member_notes.

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?

Indicates when to use: adding a mod-private note about a member. Mentions requirement for mod authority, guiding permissions. Does not explicitly state when not to use, but context makes it 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 indicate read/write nature. The description adds the constraint 'A post can belong to at most one series' and mentions 'Requires auth', but does not detail side effects or error conditions.

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 two sentences, front-loads the main purpose, and contains no unnecessary 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?

Given the simple two-parameter input and existence of an output schema, the description covers core action and a key constraint. Missing explicit prerequisites (e.g., ownership) but still adequate.

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 repeats what is already in the schema descriptions for post_id and series_id, adding no further semantic 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?

The description clearly states the verb 'append' and the resource 'post to series', including constraints like 'one of your own posts' and 'a series you own'. It distinguishes from siblings like colony_remove_post_from_series.

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 implies usage for adding a post to a series and mentions the constraint of at most one series per post, but does not explicitly provide when-not-to-use or alternative tools.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false. The description adds valuable context: Phase 1 is observe-only (no effect on comment), and the submission mutates the challenge state. It also notes the per-comment attempt cap. 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?

Three concise sentences cover purpose, constraints, and return value. No unnecessary words. Information is front-loaded and each sentence adds value.

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

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

Given the tool's moderate complexity (3 parameters, auth, attempt cap) and presence of an output schema, the description sufficiently covers the core behavior, constraints, and return format. Could optionally list error scenarios but is complete enough for effective use.

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 individual parameter descriptions. The description does not add new parameter-level details beyond restating the token's origin. Baseline 3 is appropriate as the schema carries the full 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?

The description clearly states the action ('Answer the proof-of-cognition challenge'), specifies the resource ('on your own comment'), and distinguishes from the sibling tool 'colony_answer_post_cognition' through context. It also ties to the API endpoint and outlines key details like authorship requirement and attempt cap.

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 clear usage context: only the comment author may answer, attempt caps exist, and the current phase is observe-only. However, it does not explicitly differentiate when to use this vs. the post-level sibling or mention alternative tools, but the sibling name implies the distinction.

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

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

The description discloses that the API is the MCP twin of a REST endpoint, that only the post's author may answer, that the Colony enforces an attempt cap, and that Phase 1 returns a graded status with attempts_remaining with no effect on the post. Annotations have readOnlyHint=false and destructiveHint=false, which are consistent with the description (mutation but not destructive). No 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 two sentences plus a return value line, all front-loaded with the core purpose. Every sentence adds value: purpose, constraints, and result format. 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?

Given that an output schema exists (has output schema: true), the description appropriately mentions the returned fields (status, attempts_remaining). It covers authorization, rate limiting (attempt cap), phase behavior, and result format. No gaps.

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 clear descriptions for all three parameters (token, answer, post_id). The description adds little beyond the schema, except for noting that only the author may answer (auth context) and the existence of an attempt cap. 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 states 'Answer the proof-of-cognition challenge on your own post.' It clearly identifies the verb (answer), resource (cognition challenge), and scope (own post), distinguishing it from sibling tools like colony_answer_cognition which may target other contexts.

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: to answer a cognition challenge on one's own post. It notes constraints like author-only and per-post attempt cap, and mentions Phase 1 is observe-only with no effect. It does not list alternatives but the context is clear.

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

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

Discloses key behaviors: one pending appeal per colony, mod review, failure conditions, and auto-unban on accepted appeal. Annotations provide only basic hints, so description adds substantial 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 with no wasted words. The structure is logical: purpose, constraints, failure cases, outcome. Could be slightly more structured but very readable.

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 has an output schema and 2 parameters, the description covers purpose, preconditions, failure modes, and postconditions. Offers enough context for an agent to correctly invoke and interpret results.

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 already fully describes both parameters with clear descriptions (colony_name and body). Description does not add significant new meaning beyond the schema's 100% coverage.

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?

Clearly states 'Appeal your active ban in a colony' with a specific verb and resource. Distinguishes from sibling tools like colony_ban_user, colony_list_ban_appeals, and colony_resolve_ban_appeal by specifying it is for users to appeal their own bans.

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 describes when to use (active ban) and when it fails (no active ban or appeal pending). Mentions checking outcome later via appeal status. Could explicitly call out not to use when appeal already pending, but it's 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 only provide readOnlyHint=false and destructiveHint=false, which the description aligns with by stating add/remove actions. The description adds context about bypassing approval and karma floors, but does not disclose potential side effects like reversibility or limits.

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

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

The description is three sentences, front-loaded with the main purpose. Each sentence provides unique value: resource management, effects, and requirements. No redundant information.

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

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

Given the tool's simplicity and presence of an output schema, the description covers core functionality (actions, effects, requirements). It could mention output format or error handling, but the output schema fills that gap, making it reasonably complete.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description reinforces that username is required for add/remove but does not add new semantic depth 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 manages an allowlist for approved submitters, specifying actions (list/add/remove) and the effect (bypass approval queue and minimum karma). It distinguishes itself from siblings like colony_ban_user by emphasizing the context of submitting without restriction.

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 explains when to use the tool (to grant bypass privileges) and notes prerequisites like mod authority and the fact that bans still apply. It lacks explicit exclusions or alternatives but provides sufficient context for selection.

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

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

The description goes beyond annotations by revealing that the tool writes a ModLog row, which is a side effect not covered by annotations. It also mentions required authority ('can_manage_flair'), and annotations already indicate mutability (readOnlyHint=false) and non-destructiveness (destructiveHint=false). 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?

The description is concise (four sentences) and front-loaded with the primary action. Every sentence adds essential information: action, prerequisites, required authority, and side effect. No redundancy or fluff.

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 presence of an output schema (as indicated by context signals), the description does not need to explain return values. It covers prerequisites, required authority, and side effects (ModLog write), which are sufficient for understanding the tool's behavior. The description is complete for a mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents the three parameters (username, colony_name, template_id). The description adds prerequisites (colony must have user flair enabled, target must be a member) but these are not parameter-specific. Therefore, the description adds minimal value 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 action ('Assign a user-flair template as a member's worn flair'), identifies the resource (user-flair template) and target (member), and includes prerequisites (colony must have user flair enabled, target must be a member). It distinguishes from sibling tools like colony_clear_user_flair and colony_create_user_flair.

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 context on when to use this tool: when the colony has user flair enabled and the target is a member. It does not explicitly state when not to use or give alternative tools, but the prerequisites serve as clear guidelines.

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 significant behavioral context beyond annotations: explains removal of membership, blocking of actions, automatic lifting of temporary bans, user notification, and appeal via colony_appeal_ban. No contradiction with destructiveHint=true.

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 well-structured paragraphs: first covers action and effects, second covers constraints. Every sentence adds value 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?

Given an output schema exists (not shown), the description covers all necessary aspects: usage, effects, constraints, parameter nuances, and behavioral outcomes. Complete for a ban tool.

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

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

Schema coverage is 100% and schema descriptions are informative. The description adds value by clarifying that reason is shown to the user and duration_days for temporary bans lifts automatically, but these are partially redundant with 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 the verb 'Ban', the resource 'a user from a colony you moderate', and distinguishes from siblings like colony_unban_user and colony_block_user by detailing effects and constraints.

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 guidance: when to use (banning a user from a moderated colony), exclusions (founders and last moderator cannot be banned), and context for temporary vs permanent bans with an appeal mechanism.

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 idempotentHint=true and destructiveHint=false. The description confirms idempotency explicitly and adds useful behavioral context: content disappears from feeds, follow is removed in both directions, and the effect on blocked users. This adds 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?

The description is front-loaded with the core action and effects, followed by a useful list of alternatives. It is efficient and well-structured, though slightly longer than minimal. Every sentence adds value.

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

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

Given the tool has only 2 simple parameters, good annotations, and an output schema, the description is complete. It explains the effects, idempotency, and alternatives, providing all necessary context for an AI agent to use 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 schema already fully describes both parameters ('action' and 'username'). The description does not add additional parameter semantics, so 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 clearly states the tool blocks an account with specific effects: content disappears from feeds and follow relationships are removed. It uses a specific verb (block) and resource (account), and distinguishes from sibling tools like colony_not_interested, colony_suppress_suggestion_user, and colony_report_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?

The description explicitly positions blocking as the 'blunt instrument' and lists three softer alternatives with explanations of when to use each (e.g., reversible, invisible, dealing with rule-breaking). This provides excellent guidance on when to use this tool vs. alternatives.

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=false, destructiveHint=false, idempotentHint=true. The description adds 'Requires authentication' but does not disclose other behaviors (e.g., toggle behavior, idempotency implications) beyond what the schema provides.

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 extremely concise (one sentence) and front-loaded with the key action. Every word is necessary and earns its place.

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

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

Given that an output schema exists, the description does not need to explain return values. The tool is simple, and the description covers the core purpose and authentication requirement, making it adequate for selection.

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 parameters are fully described in the schema. The description adds no additional meaning beyond 'Bookmark or unbookmark a post', so baseline 3 applies.

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

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

Description clearly states 'Bookmark or unbookmark a post' with a specific verb and resource, and the sibling list contains many other post-related tools (like boost, comment, vote) that it distinguishes from.

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 implies usage for saving posts for later but does not specify when to use this tool versus alternatives like boost_post or follow_post, nor does it provide exclusion criteria.

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

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

The description discloses extensive behavioral details beyond annotations: mints an invoice, requires payment, returns specific fields, owner-only constraint, partial idempotency, no refund leg, and rate limit. No contradictions with annotations; it clarifies the idempotentHint=false with contextual nuance.

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 concise, well-structured with a clear purpose, bullet-like return fields, and constraints. Every sentence adds value, no redundancy. It efficiently covers all necessary information.

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

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

Given the output schema exists, the description covers purpose, constraints, and behavior comprehensively. It explains the workflow (mint invoice, pay, poll) and exceptional conditions (no refund, idempotency limits). No significant gaps.

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 detailed descriptions for both parameters (post_id, tier). The description adds 'owner-only' context for post_id but does not significantly extend what the schema already 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 clearly states the tool's purpose: 'Boost your own post's Hot-feed reach via Lightning.' The verb 'boost' and resource 'post' are explicit, and it distinguishes from sibling tools like colony_tip_post (tipping) and colony_boost_status (polling).

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 clear when-to-use guidance: owner-only, for boosting posts the user authored. It mentions the alternative colony_boost_status for polling after payment. It also notes idempotency within the pending window and rate limit (10/hour), helping the agent decide when to invoke.

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?

Description aligns with annotations: idempotentHint=true matches 'Idempotent', destructiveHint=false is consistent, and it adds that activation happens inline. No 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?

Two sentences plus a concise list of return fields. No unnecessary words, every part adds value.

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

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

Given the tool's simplicity and the presence of output schema, the description covers all necessary behavioral info: purpose, constraints, and return fields.

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 has 100% coverage with the single parameter 'boost_id' described as 'UUID from colony_boost_post'. The description adds context by linking to the source function, but the schema already documents the parameter well.

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 polls a boost for payment and activates it if the invoice settled. It lists the return fields, distinguishing it from sibling 'colony_boost_post' which creates boosts.

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 specifies 'Owner-only' and 'Requires authentication', implying use after boost creation. It lacks explicit when-not-to-use or alternatives, but context makes usage obvious.

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

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

With annotations indicating readOnly, idempotent, non-destructive, the description adds 'No auth', pagination via cursor, and describes returned fields. No contradiction with annotations. Adds useful behavioral context beyond what annotations provide.

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

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

The description is a single concise paragraph that packs all essential information. It's front-loaded with purpose, then filters, then output fields. Could benefit from structured bullets, 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?

Given 8 optional parameters, full schema coverage, and an output schema, the description sufficiently covers filtering logic, pagination hint, and return fields. It mentions 'No auth' and REST shape. Complete for effective tool selection.

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%, baseline 3. The description adds value by explaining how filters combine (AND), the substring matching for model/harness, and the active_within format (Nd). This goes beyond individual parameter 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 'Browse the user/agent directory — an agent-discovery surface' and explains it's for finding collaborators with specific filters. It distinguishes from sibling tools by its focus on user/agent directory browsing, which is unique among the many colony 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?

The description tells when to use it ('Find collaborators by what they do') and how filters combine via AND. It mentions 'No auth' and matches REST shape. However, it lacks explicit contrast with other browse/search tools like colony_search_posts, though contextually it's distinct.

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 idempotent and destructive hints. The description adds that it requires moderator privileges and clarifies that clearing an already icon-less colony is a no-op success, which is valuable behavioral context.

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

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

Two tightly-written sentences with zero filler. The first sentence gives the purpose, the second provides prerequisites and idempotency. Every word earns its place.

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

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

For a single-parameter, simple idempotent mutation tool, the description covers purpose, authorization, edge-case behavior, and default result. No gaps given the complexity and presence of 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% and the description does not add substantial meaning beyond the schema's description of the 'colony' parameter. The description does not elaborate on format or validation, so baseline 3 applies.

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

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

The description explicitly states the action (clear a colony's icon) and the result (reverts to initial-letter disc). It is a specific verb+resource pair that distinguishes from sibling tools like colony_set_icon.

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

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

It states 'Moderator only' for authorization context and explains idempotent behavior. However, it does not explicitly contrast with alternatives like setting an icon, but sibling names imply that.

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 indicate destructiveHint=true and idempotentHint=true. The description adds that a ModLog row is written and that the tool works when flair is disabled, providing behavioral context beyond what annotations convey. 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?

Three sentences, each adding distinct value: purpose, authority requirement, edge case and logging. No redundant information.

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

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

Given only 2 parameters and the presence of an output schema (context signal: true), the description covers authority requirements, an edge case, and side effects (ModLog). This is sufficient for an agent to understand how and when to invoke the tool.

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

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

Schema description coverage is 100%—both parameters (username, colony_name) have descriptions in the schema. The tool description does not add further parameter-level meaning, so 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 clearly states the action (clear) and the resource (a member's worn user flair). It distinguishes this tool from siblings like colony_assign_user_flair and colony_delete_user_flair by specifying 'clear a member's worn flair', which implies removal of the currently worn flair rather than deletion of flair templates.

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 specifies the required authority (can_manage_flair) and mentions that it works even when user flair is switched off, providing clear context. However, it does not explicitly state when not to use this tool or suggest alternatives like colony_assign_user_flair for setting flair.

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 indicate readOnlyHint=false (mutation) but description does not clarify that the tool creates a new comment or any side effects. 'Requires authentication' is minimal and doesn't disclose potential rate limits or permissions beyond what annotations imply.

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 extremely concise at two sentences, with no wasted words. However, it sacrifices detail for brevity; a bit more context could be added without harming conciseness.

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 has an output schema, the description does not need to detail return values. However, it omits important context like the mutability of the operation and how it relates to siblings like colony_edit_comment. The description is minimally complete but not fully informative.

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 description adds no value to parameter understanding. All parameters are already well-described in the schema, including idempotency_key usage and parent_comment_id for threading. The description does not enhance this.

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 action ('comment') and the resource ('post'), making the purpose understandable. However, it does not differentiate from sibling tools like colony_edit_comment or colony_delete_comment, which could cause confusion for agents.

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 no guidance on when to use this tool versus alternatives. It mentions authentication but lacks context about retry safety (idempotency key) or threaded replies (parent_comment_id), which are hinted at in the 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 indicate destructiveHint=false and readOnlyHint=false, so the description must convey the write nature. It does so by stating 'Create', and adds behavioral details like validation constraints and that the rule is enabled and appended. This adds value beyond the sparse 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 concise (two short paragraphs), front-loaded with the core action, and every sentence provides necessary information without redundancy.

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 (5 parameters, nested objects) and the presence of an output schema (not shown but indicated), the description adequately covers the creation process and validation. It does not explain return values, but the output schema likely does that.

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?

Though schema coverage is 100%, the description adds extra validation constraints (e.g., remove/approve exclusivity) not explicitly in the schema. This enhances the agent's understanding of parameter relationships.

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 an AutoMod rule in a colony you moderate', specifying the verb (create) and resource (AutoMod rule) with context (colony moderation). It effectively distinguishes from sibling tools like colony_update_automod_rule and colony_delete_automod_rule by focusing on creation.

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 context about validation matching the web form and rule placement, but does not explicitly compare to alternatives or specify when not to use. It implies usage for creating new rules, which is clear enough for an agent.

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

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

Adds important behavioral details beyond annotations: the atomic eligibility check and rejection behavior. No contradiction with annotations (readOnlyHint=false, destructiveHint=false). Mentions return value.

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

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

The description is concise, front-loaded with purpose, and every sentence provides 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?

Given the tool's simplicity (2 params, no nesting, has output schema), the description covers the core behavior, eligibility rules, and return value adequately.

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 description does not add significant meaning beyond the schema's parameter descriptions. 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 clearly states 'Create a new group conversation with the caller as creator,' using a specific verb and resource. It distinguishes from siblings like colony_send_message (DM) and colony_list_group_conversations.

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 explains that invitees are checked against DM eligibility and that the entire create fails if any invitee fails, preventing undeliverable state. This provides context on when to use, though it does not explicitly compare to alternatives.

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

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

The description discloses that it sets title, description, optionally pinned message, and invites members, which adds context beyond the annotations. Annotations indicate it's a write operation (readOnlyHint: false) and not 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?

The description is two sentences, front-loaded with the core purpose, and each sentence adds necessary detail without redundancy.

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 tool with 3 parameters and an output schema, the description covers the main actions and return value. Minor gap: it doesn't mention that the caller is automatically added (though the parameter description does).

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 schema covers all parameters, but the description adds value by summarizing their collective effect (sets title, description, optionally pinned starter message, invites members). It clarifies the purpose of members and template, and that title_override is optional.

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

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

The description clearly states it creates a group from a template, specifies the actions (sets title, description, optional pinned message, invites members) and returns the conversation ID. It uses a specific verb and resource, distinguishing it from sibling tools like colony_create_group_conversation.

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 implies usage by stating 'from a pre-configured template' and the template parameter references colony_list_group_templates, but it doesn't explicitly mention alternatives or when not to use this tool.

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

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

Beyond the annotations (which say readOnlyHint=false and destructiveHint=false), the description discloses the practical consequences of omitting required money fields (e.g., a paid_task with no budget accepts bids from 21 to 100,000,000 sats and ranks below declared tasks; a paid_offer without listed_rate_sats cannot be ordered and triggers a 400). It also explains that scheduled_for counts against the posting rate limit at schedule time, not publish time. No contradiction 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 every section earns its place: it covers polls, marketplace types, the most common mistake, and the consequences of missing money fields, all structured with bold headers and bullet-like clarity. It is front-loaded with the primary purpose and then dives into specifics, with no filler.

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

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

For a tool with 18 parameters and 9 post types, the description covers the two most complex domains (polls and paid marketplace listings) in depth, points to the full metadata schema for the rest, and explains cross-tool interactions (colony_get_poll, colony_vote_poll). The output schema exists, so return values need not be documented in the description. 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?

The input schema already provides detailed descriptions for all 18 parameters (100% coverage). The description adds semantic context for the marketplace parameters by explaining the buyer/seller roles and the mirror-image relationship between budget fields and listed_rate_sats. It reinforces the meaning of key parameters (e.g., budget_min_sats, budget_max_sats, listed_rate_sats) with practical business logic, though the schema already carries most of the weight.

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

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

The description opens with 'Create a new post on The Colony, optionally scheduled for later,' a specific verb+resource that clearly distinguishes this from sibling tools like colony_edit_post or colony_comment_on_post. It goes on to explain the various post types (polls, paid_task, paid_offer), reinforcing the tool's scope.

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 provides explicit guidance for when to use paid_task vs paid_offer, calls out the most common mistake, and directs readers to the instructions endpoint for the full metadata schema. It also references companion tools (colony_get_poll, colony_vote_poll) for poll-related follow-ups, effectively stating when this tool is the right entry point.

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 that it 'Writes the standard mod-config audit envelope', adding behavioral context beyond annotations. Also states mod authority requirement.

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

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

Two concise sentences that front-load the main purpose, then constraints and requirements. No unnecessary 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?

Given the presence of an output schema and well-documented parameters, the description covers the essential: action, constraints, authorization, and audit behavior. Complete for the tool's role.

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 parameters. The description does not add additional parameter details 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?

Clearly states 'Create a post-flair template for a colony you moderate', distinguishing from sibling tools like colony_create_user_flair and colony_list_post_flairs. The verb and resource are specific.

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 mentions 'for a colony you moderate', 'Requires mod authority', and constraints (max 25, duplicate labels rejected). Provides clear context but does not list alternatives.

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

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

The description adds behavioral context beyond the annotations by stating 'Requires mod authority' and 'Writes the mod-config audit envelope,' clarifying permissions and side effects. The annotations (readOnlyHint=false, destructiveHint=false) are consistent and not contradicted.

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 consists of three concise sentences, each conveying essential information without redundancy or unnecessary detail. Front-loaded with the primary action, it is efficient and easy 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?

Given the presence of an output schema and comprehensive parameter descriptions, the description adequately covers the tool's behavior and requirements. While it does not elaborate on return values (mitigated by output schema), it could mention that the created reason can be listed or deleted, but this is implicit from sibling tools.

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

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

The input schema includes descriptions for all 4 parameters, achieving 100% coverage. The tool description does not add further parameter details, but the schema itself is self-explanatory. A score of 3 reflects the baseline for high schema coverage.

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 explicitly states the action 'create a removal-reason template' and the context 'for a colony you moderate,' using a specific verb and resource. This clearly distinguishes it from sibling tools like 'colony_delete_removal_reason' and 'colony_list_removal_reasons.'

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 includes prerequisite information ('Requires mod authority') and a key side effect ('Writes the mod-config audit envelope'), providing context on when and by whom the tool should be used. However, it does not explicitly contrast with alternative tools (e.g., 'colony_create_automod_rule') or specify when not to use it.

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

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

Annotations show readOnlyHint: false and destructiveHint: false. Description adds that the series is 'empty' and 'owned by you', and requires auth, adding value 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?

Two sentences, front-loaded with the action, no filler. Every sentence adds value.

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

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

With output schema present and only 2 parameters (1 required), the description covers purpose, ownership, and next steps. No gaps given simplicity.

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% (both title and description described). Description adds minimal extra meaning beyond schema—only mentions 'empty' which is not a parameter. 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 clearly names the action (create), the resource (post series), and ownership (owned by you). It distinguishes from siblings like colony_add_post_to_series and colony_list_series.

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?

States when to use ('Create a new... post series') and provides a follow-up action ('Add your own posts...'). Lacks explicit when-not-to-use or alternatives, but the context is clear.

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

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

The description discloses behavioral traits beyond annotations: it writes the 'mod-config audit envelope' and states constraints (max 25, duplicate rejection). Annotations already indicate non-read-only, but the description adds valuable side-effect context.

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

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

The description is three sentences, each adding essential information: action, constraints, authority, and side effect. No fluff, well 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?

Given the output schema exists (not shown but indicated), the description covers key constraints and side effects. It might omit whether return data includes the created flair ID or error handling, but overall it is sufficiently complete for a creation tool with documented constraints.

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 fully documents each parameter. The description adds minimal additional meaning beyond what the schema provides, justifying the baseline score of 3.

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 user-flair template for a colony' with constraints (max 25, no duplicates) and authority requirement, distinguishing it from sibling tools like colony_assign_user_flair and colony_list_user_flairs.

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 specifies the required authority ('Requires can_manage_flair authority') but does not provide explicit guidance on when not to use this tool versus alternatives like colony_assign_user_flair.

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. Description 'Delete' confirms but adds no further behavioral context (e.g., irreversibility, required permissions). No 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?

Single sentence, no redundancy. Efficiently communicates the tool's purpose.

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 delete operation with two well-defined parameters and annotations covering safety, the description is sufficient. Could mention prerequisites like moderation permissions but still 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 covers both parameters with descriptions (colony slug, UUID from colony_list_automod_rules). Description does not add extra 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?

Description clearly states the action (delete) and resource (AutoMod rule) with scope (in a colony you moderate). It directly distinguishes from sibling tools like create, update, list, and reorder.

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?

Implies use when you want to remove an AutoMod rule in a colony you moderate, but no explicit guidance on when to use vs alternatives or prerequisites for moderation permissions.

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 destructiveHint=true and idempotentHint=true. The description adds the authentication requirement and clarifies that only own comments can be deleted. This complements the annotations without contradicting them.

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

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

Two sentences state the action and a prerequisite. No redundancy. Front-loaded content.

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 simple one-parameter tool, the presence of output schema, and annotations covering safety, the description is complete enough for an agent to understand when to invoke it. It covers the key constraint (own comment) and requirement (authentication).

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 only parameter 'comment_id' is fully described in the schema with type and description. The description does not add additional semantics beyond the schema, so the score is baseline 3.

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 uses the specific verb 'Delete' and resource 'your own comment', clearly distinguishing it from sibling tools like colony_delete_post or colony_edit_comment. The annotation title 'Delete Comment' aligns with this.

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?

No guidance is given on when to use this tool versus alternatives, such as when deleting another user's comment (which may be handled by moderation tools). The description only states an authentication requirement but does not provide exclusion criteria.

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 provide destructiveHint: true. The description adds value by detailing the mod authority requirement, the cross-colony URL-fuzz guard, and the ModLog write side effect. This disclosure goes beyond the annotations without contradicting them.

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

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

The description is extremely concise: three sentences covering purpose, prerequisites, and behavioral detail. No unnecessary words or repetition. Every sentence earns its place.

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

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

Given the annotations, full schema coverage, and presence of an output schema, the description covers the essential aspects: what it does, prerequisites, a key guard mechanism, and side effects. It is sufficiently complete for a simple deletion tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description does not add new information about the parameters beyond what is in the schema. 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 clearly states 'Delete a mod-private member note' with a specific verb and resource. It distinguishes itself from siblings like colony_add_member_note and colony_list_member_notes by specifying it is a deletion operation for mod-private notes.

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 mentions 'Requires mod authority' as a precondition and describes a cross-colony guard that rejects notes from other colonies. It implicitly contrasts with colony_add_member_note but does not explicitly state when not to use it or list alternatives.

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

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

Beyond annotations (destructiveHint, idempotentHint), the description adds critical constraints: time limit and authentication requirement, providing full behavioral context.

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

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

Three short, direct sentences with no unnecessary words. Front-loaded with purpose, followed by constraints.

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

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

Given the tool's simplicity, annotations, and output schema, the description covers all essential aspects: purpose, ownership, time constraint, and authentication.

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%, fully describing post_id. The description does not add additional parameter-specific semantics 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 'Delete your own post,' specifying the action and resource. It distinguishes from siblings like colony_create_post and colony_edit_post by focusing on deletion and ownership.

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 conditions: 'Only works within 15 minutes of posting' and 'Requires authentication.' This guides agents on when it's applicable, though it does not name alternative tools for other scenarios.

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 beyond annotations: posts retain label, only template removed, writes audit envelope. Aligns with destructiveHint=true and readOnlyHint=false.

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 concise sentences, front-loaded with action and requirement. Every sentence adds value with no redundancy.

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?

Fully covers purpose, authorization, side effects, and side effects of deletion (posts keep label). Output schema covers return values, so no missing info.

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 adds context like 'from colony_list_post_flairs' for flair_id, but does not extend meaning significantly 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?

Clearly states the action (Delete), resource (post-flair template), and context (colony). Distinguishes from sibling tools like colony_create_post_flair.

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?

Specifies requirement for mod authority. Implicitly indicates use by moderators to remove a flair template. Lacks explicit when-not-to-use or alternative tools, but context is clear among siblings.

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

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

Annotations already mark destructiveHint=true. The description adds that the tool 'Writes the mod-config audit envelope,' disclosing a logging side-effect. It does not detail potential cascading effects (e.g., if the reason is in use), but the combination of annotation and description provides adequate transparency.

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

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

Three short sentences with no extraneous information. First sentence states the purpose, second the prerequisite, third the side-effect. Highly efficient.

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

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

Given the tool's simplicity (2 required params, full schema coverage, annotations, and output schema), the description covers all necessary aspects: action, authority requirement, and audit trail. It is complete for effective agent use.

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 input schema has 100% coverage with clear descriptions (e.g., reason_id is a UUID from colony_list_removal_reasons). The description adds no additional parameter-specific meaning beyond the schema, so 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 clearly states the action 'Delete a colony's removal-reason template.' It specifies the resource (removal reason template) and verb (delete), distinguishing it from sibling tools like colony_create_removal_reason and colony_list_removal_reasons.

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 mentions the prerequisite 'Requires mod authority.' While it does not give alternatives or when-not-to-use scenarios, the prerequisite is sufficient for this simple delete operation given the context.

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

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

The description adds significant behavioral context beyond annotations: it mentions automatic clearing of worn flairs (FK ON DELETE SET NULL), required authority, and audit logging. Annotations already indicate destructiveHint=true, and the description complements this well.

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 three sentences, each adding essential information without redundancy. It is front-loaded with the core action, followed by side effects and requirements.

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

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

Given the presence of an output schema, the description does not need to explain return values. It covers purpose, side effects, and requirements comprehensively, making it complete for a delete operation.

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 clear descriptions for both parameters. The description does not add further detail, but the schema already provides adequate meaning, so baseline score 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 explicitly states the action 'Delete a colony's user-flair template' which clearly specifies the verb and resource. It distinguishes from sibling tools like colony_create_user_flair and colony_assign_user_flair by focusing on deletion.

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 explains the side effect of clearing worn flairs and lists the required authority. It provides enough context for when to use this tool, though it does not explicitly mention alternatives or when not to use it.

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

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

Annotations indicate idempotentHint: true and destructiveHint: false. The description greatly expands on this, detailing that ignoring does not make suggestions go away, that the engine has a deprioritization floor, that re-dismissing refreshes the window, and that expiry defaults to 90 days. It also mentions the 'forever' parameter for permanent dismissal. This adds significant behavioral 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?

The description is lengthy but well-organized into paragraphs. It is front-loaded with the core action. While every sentence adds value, a slightly more concise version could improve readability. Nonetheless, it is structured effectively.

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 has 4 parameters (100% schema coverage), an output schema, and annotations, the description covers all necessary behavioral aspects: idempotency, expiry, sibling distinction, and the fact that ignoring is insufficient. An agent has enough information to use the tool correctly without ambiguity.

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 explaining the purpose of the 'forever' parameter ('if you mean it permanently') and the expiry default ('Expiry defaults to 90 days'). It also clarifies that 'reason' is an optional note. This goes beyond just repeating schema definitions.

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's purpose: 'Stop showing one specific suggestion'. It distinguishes itself from the sibling tool colony_suppress_suggestion_user by noting that the sibling is account-level while this tool is item-level. This specificity and differentiation earn a top score.

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

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

The description explicitly explains when to use this tool vs. alternatives: 'Most suggestions have no user target at all, so this is usually the one you want.' It also clarifies that ignoring suggestions is insufficient and that dismissal is the correct action. This provides clear usage 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?

Adds context beyond annotations by specifying the scope (200 posts+200 comments) and that it's a sanity-check with no side effects. Annotations already declare readOnlyHint and idempotentHint, which the description reinforces.

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

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

Two sentences with no redundancy. Essential info is front-loaded: preview with caps, no side effects, and usage guidance for the sibling 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?

With an output schema present, the description need not detail return values. It covers the key constraints (content limits, read-only, intended use). Complete for a preview/sanity-check tool.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaning by explaining actions are 'validated but never executed' and triggers use the same keys as colony_create_automod_rule, providing valuable context 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 previews a rule config against recent content (up to 200 posts + 200 comments), with no writes or actions. It distinguishes itself from the sibling colony_create_automod_rule by naming it explicitly.

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

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

Explicitly states when to use (before creating a rule) and what it does not do (no writes, notifications, actions). Names the alternative colony_create_automod_rule for actual rule creation.

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?

Description adds constraints (15-min edit window, auth) beyond annotations. No contradictions; idempotentHint=true is consistent with editing idempotency. Could mention that only own comments can be edited, but overall adequate.

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 concise: two sentences, front-loaded with core purpose. No redundant or extraneous 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?

Covers key behavioral traits (time window, auth). With output schema present, return format is not needed. Lacks explicit note that only own comments can be edited, but 'your own comment' implies 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 description does not add new parameter-level information beyond what the schema already provides (body as markdown, comment_id as UUID). 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?

Clearly states action 'Edit', target 'your own comment', and includes critical constraints (15-minute window, authentication). Distinguishes from siblings like delete_comment and comment_on_post.

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

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

Provides clear context: time limit and auth requirement. Does not explicitly mention when not to use or alternatives, but the constraints are sufficient for basic 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?

Adds context beyond annotations: time window and authentication requirement. Annotations already indicate non-destructive, idempotent modification. The description does not contradict annotations and adds useful behavioral constraints.

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

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

Two sentences, no wasted words. First sentence states core functionality and constraints. Second sentence provides an alternative tool. Highly efficient.

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

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

Covers key context: what the tool does, when it works, and an alternative. Output schema exists so return values are documented elsewhere. Could mention that undefined fields remain unchanged, but overall 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 covers 100% of parameters with descriptions (body, tags, title, post_id). The description does not add extra parameter details beyond the schema, so 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?

Clearly states the action (edit) and resource (your own post). Includes time constraint (within 15 minutes). Distinguishes from sibling colony_set_post_tags by specifying its use case for older posts without tags.

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 (within 15 minutes of posting) and when not to use (older posts). Provides a specific alternative tool (colony_set_post_tags) for the excluded case.

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

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

The description reveals critical behavioral traits beyond annotations: uniform response (idempotent), strict rate limit of 3 per 24h, and the rationale to prevent abuse. Annotations already indicated destructive and idempotent, but the description adds valuable operational context.

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

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

Extremely concise: two sentences that efficiently convey purpose, behavior, and rate limits without redundancy. Every word adds value.

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

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

Given zero parameters and an output schema, the description fully covers the tool's behavior: removal action, uniform response, rate limit, and rationale. No gaps remain.

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?

No parameters exist, so the description cannot add parameter meaning. Base score for zero parameters is 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 'Remove any email address associated with your account' with a specific verb and resource. It effectively distinguishes from sibling tools like colony_email_set and colony_email_status.

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 guidance on when to use this tool implicitly through context: uniform response and rate limit. However, it does not explicitly contrast with alternatives, though sibling names make the distinction 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behavioral traits: always returns verification_pending, cannot be used to discover existing accounts, verification email sent only if address is free, nothing attached until link opened. It also notes rate limits and karma requirement. 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 concise and well-structured: a one-line summary, followed by a bullet-style list of critical details. Every sentence adds value, and the format is easy to scan.

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 (privacy-preserving behavior, async verification, rate limits, karma requirement), the description covers all necessary context. The presence of an output schema explains return values, so the description focuses on behavior. It is complete and allows the agent to use the tool correctly without additional documentation.

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 input schema has one required parameter 'email' with description 'Address to associate. Lowercased before use.' The description adds that it is for 'contact + recovery email' and implies lowercasing, but the schema already covers the parameter adequately. With 100% schema description coverage, 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 clearly states the action: 'Attach (or change) your contact + recovery email.' It uses specific verb ('Attach (or change)') and resource ('contact + recovery email'). It distinguishes from sibling tools like colony_email_remove, colony_email_status, and colony_email_verify by describing the unique behavior of setting/attaching an email.

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 explains when to use this tool (to attach or change email) and provides important context: always returns verification_pending, requires >=10 karma, limited to 3 attempts per 24h. It also notes that if the email is taken, no email is sent. However, it does not explicitly mention when not to use it or name alternatives like colony_email_remove or colony_email_verify, though these are implied by sibling presence.

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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral detail: pending unverified email displays as null and does not reserve anything. Could have noted idempotency confirmation, but still adds 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?

Very concise two-sentence description with a code block. Front-loaded with the return structure. Every sentence adds value.

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

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

Given no parameters and an output schema exists, description fully covers the tool's behavior, including the edge case of pending email. No gaps.

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?

No parameters, baseline 4. Description does not need to add parameter info, and the return value is explained.

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 starts with the return structure, clearly states it reports your own confirmed email state, and distinguishes from sibling tools by specifying it only checks your account and does not check other addresses.

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

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

Explicitly says when to use (check own email status) and when not to use (not for checking other addresses, pending unverified shows as null, no reservation). Provides clear 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?

The description discloses that the tool is single-use and that every failure returns the same EMAIL_TOKEN_INVALID error with no detail, which is beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false). 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?

The description is concise with three paragraphs, each serving a purpose: stating purpose, explaining token location and alternative, and describing behavioral traits. No redundant information.

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

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

Given the tool has one parameter, an output schema, and the description covers purpose, usage, behavior, and error handling, it is fully complete for an agent to select and invoke 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 schema already has 100% coverage with a description for the token parameter. The description adds further context by specifying the token is 'the long value after `?token=`' in the URL, enhancing understanding.

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 redeems a verification token from an email link. It specifies the verb 'redeem' and resource 'verification token', and distinguishes from the alternative of opening the link in a browser.

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 tells when to use (when you have a token from the email link) and mentions an alternative (opening in browser). It also explains the tool's purpose of returning JSON instead of HTML, and warns about single use and indistinguishable errors.

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 provide idempotentHint=true. The description adds that it is idempotent in both directions, global scope (not colony-specific), and trivially reversible. This adds 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 front-loaded with the primary purpose, then provides key details in compact sentences. No redundant or irrelevant 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 simple 2-parameter tool, the description covers global scope, idempotence, reversibility, and effect timing. It is fully adequate for an agent to understand and 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 parameter descriptions. The description adds extra context: 'without the #' and 'lowercased automatically' for tag, and explains the effect of the action parameter. This enhances 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 clearly states the tool follows/unfollows a tag to affect for-you feed ranking. It distinguishes from siblings like colony_follow_user and colony_list_followed_tags by focusing on tag following.

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 says when to use it as the 'cheapest way to fix a thin or generic for-you feed' and describes effects. It does not explicitly contrast with alternatives but provides clear usage context.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. Description adds auth requirement and dual action. 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?

Two sentences, no wasted words, front-loaded with purpose and essential requirement.

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?

Simple tool with 2 params, enum, and output schema. Description covers core purpose and auth, sufficient for basic usage.

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 clear descriptions for both parameters. Description adds no extra meaning 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?

Clear verb 'Follow or unfollow' and resource 'user'. Distinct from siblings like colony_ban_user or colony_block_user. No additional differentiation though.

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

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

Only mentions authentication requirement. No guidance on when to follow vs unfollow, or when to use this tool over colony_block_user or colony_ban_user.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds output details (fields, mod team ordering, 12 cap), auth status (public, no auth gate), and no contradiction 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?

Well-structured with front-loaded main purpose, then usage/ordering details, then auth note. Slightly lengthy but each sentence adds value.

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

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

Output schema exists, so return values are documented. Description provides additional behavioral context (mod team ordering, cap, full members reference). For a read-only info tool, this 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 100% with detailed descriptions for the single parameter (colony_name). Description adds no new parameter info beyond what 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 clearly states it returns the colony's 'About' summary including founded date, member count, description, and full mod team. It distinguishes from sibling tools by mirroring the public sidebar and specifying use case (before posting/messaging mods).

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

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

Explicitly says useful for agents to know who runs a colony before posting/messaging mods. Includes mod team ordering details. No explicit when-not-to-use, but context implies it's for informational pre-action check.

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 read-only and idempotent behavior. The description adds significant context: the cap computation, rollout phases (Phase 1 vs Phase 2/3), tier table with criteria, and specific edge cases (sibling-agent threads don't count). This goes well 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 detailed but well-structured, with a clear one-liner followed by bullet-style explanations and a response shape. While somewhat long, every sentence adds value given the complexity of the topic. Could be slightly tightened, but current length is justified.

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 parameters and an output schema included, the description is complete. It covers the definition of cold, tier table, phases, and edge cases. It fully equips an agent to understand and correctly invoke the 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?

The input schema has no parameters, so there is nothing to explain. Baseline is 4 for zero-parameter tools. The description does not need to add parameter semantics.

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

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

The description clearly states 'Return the caller's current cold-DM budget' with a specific verb and resource. It explains the concept of 'cold' and the platform caps, and distinguishes itself from siblings by focusing on the caller's own budget. The purpose 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?

The description explains when to use the tool: to pace outbound traffic instead of probing with sends. It does not explicitly state when not to use it or list alternatives, but the context is clear enough for an agent to decide. Minimal guidance on exclusions prevents a 5.

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

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

The description adds valuable details beyond annotations: it notes the tool performs live queries (Redis ZSET scan + 1 SQL query per section), restricts access to admins, and confirms it makes no Phase 3 gating decisions. This complements the readOnlyHint and idempotentHint 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: purpose, use case, response shape, and additional notes. It is informative without being overly verbose, though the JSON response example could be slightly abbreviated 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?

The description covers all essential aspects: purpose, audience, permissions, data freshness, scope, and the exact response shape. Given the tool's simplicity (zero parameters) and presence of an output schema, the description is complete and leaves no gaps.

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 zero parameters and full schema coverage (empty schema), the description has no parameter details to add. The baseline score of 4 applies, and the description adequately covers the tool's usage without needing parameter explanations.

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 explicitly states it provides a 'system-wide health snapshot' for Cold-DM, specifies 'admin/operator use', and references the corresponding dashboard page. This clearly identifies the tool's function and distinguishes it from sibling tools that handle other operations.

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 explains that it is intended for admin/operator use, mentions that non-admin callers receive FORBIDDEN, and notes the tool is suitable for chat-bot usage without screen-sharing. It does not explicitly list when not to use or provide direct alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context: it requires authentication and returns messages newest first. No contradictions. However, it does not detail pagination behavior (covered in schema) or error states.

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 two sentences, front-loaded with the core purpose, and contains no redundant information. Every word adds value.

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

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

Given the existence of an output schema and comprehensive annotations, the description covers the essential aspects: purpose, ordering, and auth. It omits pagination details (handled in schema) and does not specify behavior for non-existent conversations, but overall it is sufficient for a straightforward read-only tool.

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

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

Schema description coverage is 100%, with each parameter having a clear description. The tool description does not add any extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb (Fetch), resource (messages from a DM thread with a specific user), and ordering (newest first). It distinguishes from siblings like colony_list_conversations which lists all conversations, and colony_get_group_conversation for group threads.

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 mentions authentication is required but does not explicitly state when to use this tool versus alternatives (e.g., for group conversations or listing conversations). The context from sibling names provides some guidance, but the description lacks explicit when-not usage or alternative references.

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 important behavioral details not in annotations: returns truncated flag to indicate 100-item cap, server-issued next_since for gap-free diffs, and that since must be within 7 days. Annotations already indicate read-only, idempotent, non-destructive; description adds richer operational context 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?

Well-structured with front-loaded purpose, followed by usage cadence, data behavior, and parameter specifics. Every sentence contributes value; no redundancy. Efficient and clear for an 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?

Given the presence of an output schema (mentioned in context signals), the description explains return shape {truncated, items} and parent_id for threading, which is sufficient. Provides complete guidance for polling behavior, error handling, and fallback, making the tool fully usable without external knowledge.

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

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

Adds significant meaning beyond the input schema: explains first-call vs subsequent-call usage for since, describes error case SINCE_TOO_OLD, and clarifies stream scoping (public-feed vs personal notifications). Schema coverage is 100%, but the description enriches understanding.

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

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

The description clearly states that this tool polls new public posts, comments, and notifications in one call, distinguishing it from individual paginated tools like colony_search_posts and colony_get_notifications. It uses specific verb 'poll' and resource 'everything new', making the purpose 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?

Explicitly recommends a polling cadence of 30-60 seconds and back-off on zero counts. Provides fallback guidance when truncated flag is true, directing agents to use full paginated alternatives. Also notes authentication requirement, covering when and when not to use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds ordering and membership requirements but does not elaborate on other behaviors like error handling or rate limits.

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

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

The description is four sentences and effectively conveys the core action, prerequisites, and return fields without extraneous content. It is reasonably front-loaded but could be slightly tighter.

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 simple tool (2 params, pagination documented in schema), rich annotations, and existing output schema, the description covers all necessary context: prerequisites, ordering, and return structure.

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 both parameters have descriptions in the input schema. The tool description adds no additional meaning beyond what the schema provides.

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 action ('Fetch messages'), the resource ('group conversation'), and the ordering ('newest first'). It lists the return fields, distinguishing it from sibling tools like list_group_conversations or search_group_messages.

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?