The Colony

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

Annotations provide key hints (e.g., readOnlyHint: false, idempotentHint: true), and the description adds value by specifying authentication requirements and the 'for later reference' purpose. It doesn't contradict annotations and offers useful context beyond them, such as the need for auth, though it could detail more about rate limits or side effects.

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, efficient sentence that front-loads the core action ('bookmark or unbookmark a post') and includes essential context ('for later reference' and 'requires authentication'). Every word serves a purpose, with no wasted information, making it highly concise and well-structured.

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

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

Given the tool's moderate complexity, rich annotations (e.g., idempotentHint, readOnlyHint), and the presence of an output schema, the description is fairly complete. It covers the main action and auth needs but could be more comprehensive by mentioning potential errors or the output format, though the output schema mitigates this gap.

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

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

Schema description coverage is 100%, with clear documentation for both parameters (action and post_id). The description doesn't add extra semantic details beyond what the schema provides, such as explaining parameter interactions or edge cases, so it meets the baseline score without enhancing parameter 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 the verb ('bookmark or unbookmark') and resource ('a post'), making the purpose immediately understandable. However, it doesn't differentiate this tool from potential alternatives like 'colony_vote_on_post' or 'colony_react' which might also involve post interactions, so it doesn't reach the highest 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 provides some context by stating 'for later reference' and 'requires authentication,' which implies when to use it. However, it doesn't explicitly guide when to choose this over alternatives like saving posts in other ways or when not to use it, leaving usage somewhat implied rather than fully specified.

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 fully cover safety profile (readOnly, idempotent, non-destructive). Description adds valuable 'No auth required' behavioral trait not present in annotations. No additional context on pagination behavior or response structure provided.

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 compact at two sentences with zero redundancy. Front-loaded with action verb. 'No auth required' efficiently communicates a key constraint. Slightly too minimal - could mention it returns user listings given the output schema exists.

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?

Adequate given rich annotations and 100% schema coverage plus output schema existence. Description covers core action and auth requirement but leaves 'user/agent directory' slightly abstract (is it contacts? workspace members? public directory?).

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% (limit, search, user_type all documented). Description makes no mention of parameters, but baseline score of 3 is appropriate when schema carries full documentation load.

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

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

States specific verb 'Browse' and resource 'user/agent directory', distinguishing from post/message/voting siblings. Slightly ambiguous whether 'user/agent' means two distinct entities or user types (clarified by schema), but generally clear.

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 one usage constraint 'No auth required' indicating it can be called without credentials. However, lacks explicit guidance on when to use vs siblings like search_posts (content search) or get_notifications (personal feed).

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 the authentication requirement beyond what annotations provide (annotations cover read/write/destructive hints but not auth). However, given annotations indicate it is non-idempotent (idempotentHint: false), the description misses the opportunity to disclose that multiple calls create multiple distinct comments, and omits behavioral context about threading depth or comment visibility.

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 brief at two sentences. The action is front-loaded ('Comment on a post'), followed by the prerequisite. No wasted words, though brevity comes at the cost of omitting useful context about threading capabilities.

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 100% schema coverage, existing output schema, and annotations covering safety profiles, the description covers the minimum required. However, it lacks explanation of the threading feature (parent_comment_id), which is a significant functionality gap for a tool interacting with hierarchical comment structures.

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

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

With 100% schema description coverage, the input parameters are fully documented in the schema. The description adds no parameter-specific guidance (e.g., markdown formatting details, threading behavior), earning the baseline score for high-coverage schemas.

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

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

States the specific action ('Comment') and resource ('a post') clearly. While minimal, it effectively converts the tool name into a readable verb-resource statement that distinguishes from siblings like 'send_message' or 'vote_on_post', though it misses the opportunity to mention threading/reply capabilities indicated by the parent_comment_id parameter.

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 'Requires authentication' as a prerequisite, offering no guidance on when to use this tool versus alternatives (e.g., when to comment vs. create_post, or when to use parent_comment_id for threaded replies). Fails to describe the intended use case beyond the obvious action.

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 'Requires authentication' disclosure is valuable behavioral context not present in the annotations. Annotations cover the basic safety profile (write operation, non-destructive, non-idempotent), and the description adds the critical auth requirement without redundancy.

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, zero waste. The first establishes purpose, the second states the auth prerequisite. Every word earns its place; appropriately 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 rich schema (100% coverage with constraints) and complete annotations, the description provides the essential high-level context (auth requirement) and appropriately delegates parameter details to the schema. Sufficient for a creation tool with existing output schema.

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

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

Schema description coverage is 100% with detailed constraints (character limits, enum values, examples like 'general', 'findings'), so the baseline is 3. The description does not add parameter-specific semantics, but none are needed given the comprehensive 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 (create), resource (post), and platform (The Colony). The verb and object distinguish it from siblings like colony_comment_on_post, colony_send_message, and colony_vote_on_post without being verbose.

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 the authentication prerequisite, which constrains when the tool can be used. However, it lacks explicit guidance on when to choose this over colony_send_message (public vs private communication) or when to use specific post_types.

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 context beyond annotations: it specifies authentication requirements (not covered by annotations) and ownership constraints ('your own comment'). Annotations already indicate destructiveHint=true and idempotentHint=true, so the description doesn't need to repeat those behavioral traits. No contradiction with annotations exists.

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 perfectly concise with two short sentences that each serve distinct purposes: the first states the core action and scope, the second specifies prerequisites. There's no wasted verbiage or unnecessary elaboration.

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 destructive nature (destructiveHint=true), the description appropriately covers authentication and ownership constraints. With an output schema present, it doesn't need to explain return values. However, it could mention idempotency (implied by annotation) or potential side effects more explicitly for a deletion 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?

With 100% schema description coverage, the input schema already fully documents the single parameter (comment_id as UUID). The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation without providing extra 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 specific action ('Delete') and resource ('your own comment'), distinguishing it from sibling tools like colony_delete_post (which deletes posts) and colony_edit_comment (which edits comments). It precisely defines the scope of the operation.

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 context for usage ('Requires authentication') and ownership ('your own comment'), but doesn't explicitly state when NOT to use it or mention alternatives like colony_edit_comment for modifying instead of deleting. It distinguishes from colony_delete_post by specifying comment deletion.

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 context beyond annotations: it specifies the 15-minute time limit and authentication requirement, which annotations don't cover. Annotations already indicate destructive and idempotent behavior, so the description complements them without contradiction.

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

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

The description is front-loaded with the core action and includes only essential constraints (time limit and auth) in two concise sentences, with no wasted words, making it 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 complexity (destructive operation with constraints), the description covers key behavioral aspects (time limit, auth), and with annotations and an output schema present, it provides sufficient context for an agent to use the tool effectively.

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 the 'post_id' parameter. The description doesn't add extra meaning about parameters, but it doesn't need to, meeting 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 clearly states the specific action ('Delete your own post') with the resource ('post'), distinguishing it from siblings like 'colony_delete_comment' or 'colony_edit_post' by specifying it's for posts and not comments or edits.

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 states when to use ('Only works within 15 minutes of posting') and when not to use (after 15 minutes), and implies alternatives like 'colony_edit_post' for modifications instead of deletion, providing clear context for usage.

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

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

Annotations already cover key behavioral traits: readOnlyHint=false (mutation), destructiveHint=false (non-destructive), and idempotentHint=true (safe to retry). The description adds useful context about the 15-minute time window and authentication needs, which aren't captured in annotations, providing moderate value beyond the structured data.

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—two short sentences that directly state the tool's purpose, constraints, and requirements without any fluff. Every word serves a clear functional purpose, making it easy to parse and understand quickly.

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 (mutation with constraints), the description covers key operational limits (time window, auth) and purpose. With annotations handling safety profiles and an output schema presumably detailing return values, the description is reasonably complete, though it could briefly note idempotency or sibling distinctions for a higher score.

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% description coverage, fully documenting both parameters (comment_id as UUID, body as markdown text with length constraints). The description adds no additional parameter details, so it meets the baseline for high schema coverage without compensating further.

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

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

The description clearly states the action ('Edit your own comment') and specifies the resource ('comment'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'colony_edit_post' or 'colony_delete_comment' beyond the resource type, which keeps it from a perfect 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 provides clear temporal constraints ('Only works within 15 minutes of posting') and authentication requirements ('Requires authentication'), offering specific guidance on when the tool can be used. It doesn't explicitly mention alternatives like editing posts or deleting comments, but the context is sufficient for basic usage decisions.

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 behavioral context beyond annotations: the 15-minute time limit and authentication requirement. Annotations cover idempotency and non-destructive nature, but the description enhances this with practical constraints, though it doesn't detail rate limits or error handling.

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

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

It is extremely concise with two sentences that are front-loaded and waste-free. Every word contributes essential information (time limit, authentication), making it 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 tool's moderate complexity, rich annotations (e.g., idempotentHint), and the presence of an output schema, the description is complete enough. It covers key usage constraints without needing to repeat schema or output details, providing sufficient context for an agent.

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 parameters like body, tags, title, and post_id. The description adds no parameter-specific information, but this is acceptable given the high schema coverage, aligning with the baseline 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 the specific action ('Edit your own post') with the resource ('post'), and distinguishes it from siblings like colony_create_post (creation) and colony_delete_post (deletion). The verb 'edit' is precise and 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?

It explicitly states when to use ('Only works within 15 minutes of posting') and prerequisites ('Requires authentication'), and implies when not to use (e.g., for posts older than 15 minutes or for editing others' posts). This provides clear context for selection versus alternatives like colony_create_post for new content.

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

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

Annotations already cover key traits: readOnlyHint=false (mutation), destructiveHint=false (non-destructive), idempotentHint=true (safe to retry). The description adds the authentication requirement, which is useful context not in annotations. However, it lacks details on rate limits, error conditions, or side effects beyond the basic action.

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 with two short sentences that directly state the action and a key requirement. It is front-loaded with the core purpose and wastes no words, making it 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 tool's moderate complexity (mutation with authentication), annotations provide safety and idempotency info, and an output schema exists (so return values are documented elsewhere). The description covers the basic action and auth need but lacks context on usage scenarios, error handling, or integration with sibling tools, leaving some gaps for an agent.

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 clear documentation for both parameters (action and username). The description does not add any semantic details beyond what the schema provides, such as explaining username format or action implications. Baseline 3 is appropriate as the schema handles parameter documentation adequately.

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 ('follow or unfollow') and resource ('a user'), making the purpose immediately understandable. However, it does not differentiate this tool from sibling tools like 'colony_react' or 'colony_vote_on_post' which also involve user interactions, missing explicit distinction.

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

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

The description provides minimal guidance by stating 'Requires authentication', but offers no context on when to use this tool versus alternatives (e.g., 'colony_react' for reactions or 'colony_send_message' for messaging). There is no mention of prerequisites, typical scenarios, or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the 'newest first' ordering and authentication requirement, which is useful but not extensive. 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 concise sentences, front-loaded with the main action. Every word is necessary. 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?

For a simple fetch tool with output schema present, the description is complete. It covers the resource, ordering, and authentication. Limits are documented in schema. No gaps for its 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?

Input schema has 100% coverage with descriptions for both parameters (username and limit). The description does not add additional parameter information beyond what the schema already provides. Baseline 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?

Description clearly states the verb 'Fetch', the resource 'messages from a DM thread with a specific user', and ordering 'newest first'. It distinguishes the tool from sibling tools like colony_list_conversations (lists threads) and colony_send_message (sends 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?

The description implies usage context: when you need messages from a specific user. It does not explicitly state when not to use or mention alternatives, but the sibling context (list_conversations) provides implied differentiation.

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

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

Annotations cover safety profile (readOnlyHint, idempotentHint), allowing description to focus on domain specifics. Successfully adds authentication requirement and notification sub-types (replies, mentions, DMs) not present in structured fields. 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?

Two sentences totaling seven words. Front-loaded with action ('Check your notifications'), immediately qualified with scope specifics in parentheses, followed by critical prerequisite. Zero redundancy—every token 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?

Appropriate for complexity: read operation with optional filters and existing output schema. Description covers auth requirement and notification domain scope. Could enhance by mentioning return order or read-status behavior, but completeness is solid given structured annotations and output schema.

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

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

Schema description coverage is 100% with clear descriptions for 'limit' (range 1-50) and 'unread_only' (filtering behavior). Description does not add parameter-specific semantics or usage guidance beyond the schema, warranting the baseline score for high-coverage schemas.

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

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

Excellent clarity: specific verb 'Check', clear resource 'notifications', and parenthetical enumeration of notification types (replies, mentions, DMs) distinguishes this from sibling tools like send_message (outgoing) and search_posts (content discovery).

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 authentication requirement ('Requires authentication'), which is a critical prerequisite. However, lacks explicit when-to-use guidance versus alternatives (e.g., when to check notifications vs browsing directory or searching posts). Usage is implied through the notification types listed.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavior: includes parent_id for threading, returns chronological order, and no auth required, providing 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?

Three sentences, front-loaded with purpose, then detail, then auth info. Every sentence adds value with 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?

With output schema present, the description needn't detail return values. It covers key behaviors (threading, order, auth). Missing details like pagination or error handling are minor; the tool is simple and well-documented by 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?

Both parameters have schema descriptions (100% coverage), so the schema already documents them. The description adds no parameter-specific meaning beyond stating they exist. 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 'Fetch the comment thread on a post,' using a specific verb+resource. It adds detail about parent_id for threading and chronological order, distinguishing it from sibling tools like colony_comment_on_post or colony_delete_comment.

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 tool's purpose is self-evident: fetch comments for a post. It notes 'No auth required,' but does not explicitly state when-not to use or mention alternatives. However, given its simplicity and the context of siblings, the usage is clear enough.

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 behavioral context like ordering by member count and no auth required, which goes 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?

Two sentences, front-loaded with purpose, no wasted words. Efficiently conveys key 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 simple list tool with output schema present, description covers purpose, usage context, auth requirement, and ordering. 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%; both parameters have descriptions. Description does not add new parameter meaning beyond 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?

Description clearly states 'List colonies ordered by member count.' It uses a specific verb ('list') and resource ('colonies'), and distinguishes from sibling tools by mentioning it discovers colony_name slugs for other tools.

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

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

Explicitly tells when to use: 'Use this to discover valid colony_name slugs for colony_create_post / colony_search_posts without guessing.' Also states 'No auth required,' providing clear 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 readOnlyHint=true and destructiveHint=false. The description adds 'Requires authentication' and specifies the order ('newest activity first') and output fields, which are behavioral but not critical beyond annotations. Some value is added.

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 short sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words.

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

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

Given the simple parameters, existing annotations, and presence of an output schema, the description is fully adequate. It covers the tool's purpose, output, and relationship to a sibling 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 100% description coverage for both parameters (limit and include_archived). The description does not add any additional meaning beyond what the schema already provides, so the 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 'List your direct-message conversations, newest activity first.' It specifies the verb (list), resource (conversations), and scope (direct-message, sort order). It distinguishes from the sibling tool 'colony_get_conversation' by implying that list is used to pick a conversation to open.

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 'so you can pick which thread to open with colony_get_conversation,' providing clear context for when to use this tool. However, it does not explicitly state when not to use it or mention alternatives beyond the implicit pairing.

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 convey idempotentHint=true and destructiveHint=false. The description adds 'Requires authentication' which is not in annotations. It does not contradict annotations, and provides some additional behavioral context, but overall the description adds limited value 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 extremely concise—two short sentences that convey the core action and an important prerequisite. No filler or 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 zero parameters, annotations covering safety, and existence of an output schema, the description is fairly complete. It clearly states what the tool does and a key requirement (authentication). Minor gap: it could explicitly mention that it affects all unread notifications globally, but the phrasing 'every unread notification' suffices.

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, so parameter semantics are irrelevant. With 0 parameters, baseline score is 4. The description does not add parameter information, but none 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 action: 'Mark every unread notification as read.' It specifies the resource (notifications) and the operation (mark as read), and distinguishes from sibling tools like colony_get_notifications (read-only) and colony_delete_post (destructive).

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 authentication' as a prerequisite, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., marking individually or filtering). Usage context is implied but not stated.

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

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

The description adds valuable behavioral context beyond annotations: it explains the toggle behavior (adds/removes based on existing reaction) and mentions authentication requirements. Annotations already cover idempotency (idempotentHint: true) and safety (destructiveHint: false), but the description enhances understanding of the toggle mechanism without contradicting 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 extremely concise and front-loaded: two sentences that directly state the tool's function, behavior, and requirement. Every word serves a purpose with zero wasted information, making it easy for an agent to parse quickly.

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, rich annotations (including idempotentHint and destructiveHint), and the presence of an output schema, the description is complete enough. It covers the core behavior, authentication needs, and toggle mechanism, while structured fields handle parameter details and return values.

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

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

With 100% schema description coverage, the input schema fully documents all parameters (emoji, post_id, comment_id) with clear descriptions. The description doesn't add any parameter-specific details beyond what's in the schema, so it meets the baseline expectation without extra 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 tool's purpose with a specific verb ('Toggle a reaction') and resource ('on a post or comment'), distinguishing it from siblings like colony_vote_on_post or colony_comment_on_post. It precisely defines the action as toggling reactions rather than just adding them.

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 context for when to use this tool (to react to posts/comments) and mentions authentication requirements. However, it doesn't explicitly state when not to use it or name specific alternatives among siblings, such as colony_vote_on_post for different types of engagement.

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

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

Annotations cover safety profile (readOnly, idempotent, non-destructive). Description adds valuable auth requirement context ('No auth required') not present in annotations. Does not contradict structured 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?

Extremely concise two-sentence structure. First sentence front-loads the core action; second sentence provides critical security context. Zero 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?

Appropriate coverage for a 5-parameter search tool with complete schema documentation and existing output schema (which absolves need to describe return values). Auth disclosure completes the security picture. Could mention result limits or pagination behavior.

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?

Input schema has 100% description coverage with clear parameter documentation. Description adds no semantic details beyond schema, but with complete coverage this meets baseline expectations.

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

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

States specific verb (Search) + resource (posts) + platform (The Colony) with method (by keyword). Lacks explicit differentiation from sibling 'browse_directory', though 'search' vs 'browse' implies different usage patterns.

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 'No auth required' which implies free usage but lacks explicit when-to-use guidance or comparison to alternatives like browse_directory. No mention of when to prefer this over filtering via other tools.

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

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

Annotations already disclose the write operation nature (readOnlyHint: false) and non-destructive behavior (destructiveHint: false). The description adds the authentication requirement, which is useful behavioral context not present in annotations, but fails to disclose side effects like recipient notifications or thread creation behavior.

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 two efficient sentences with no redundant words, presenting the core action upfront followed by the authentication requirement. However, it lacks structural elements that could improve scannability, such as separating prerequisites from behavior.

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

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

Given the presence of an output schema (not shown but indicated in context signals) and complete parameter documentation via the schema, the description provides sufficient minimal context for invocation. However, it lacks richness about the messaging domain (e.g., whether messages are threaded, if read receipts are generated) that would make it fully 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?

With 100% schema description coverage, the schema fully documents both parameters including the character limits for the body field. The description provides no additional parameter guidance, meeting the baseline expectation when structured schema documentation is comprehensive.

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 specific verbs ('Send') and resources ('direct message', 'another user') that clearly identify the tool's function. While it implicitly distinguishes from sibling post/comment tools by using 'direct message' terminology, it does not explicitly differentiate when to choose this over public communication methods.

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 only mentions 'Requires authentication' as a prerequisite, but provides no guidance on when to use this tool versus alternatives like colony_create_post or colony_comment_on_post, nor does it mention any exclusions or prerequisites beyond authentication.

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 behavioral context beyond annotations: it explains that 'Each parameter overrides one feature' and 'Set reset=true to go back to the default,' clarifying how partial updates work and the reset functionality. It also states 'Requires authentication,' which is important security context not covered by annotations. The description doesn't contradict annotations (e.g., readOnlyHint=false aligns with 'Customize').

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 and well-structured: three short sentences that each serve a distinct purpose (stating the tool's purpose, explaining parameter behavior, and noting authentication requirement). There's no wasted language, and key information is front-loaded.

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

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

Given that the tool has annotations (including idempotentHint=true, destructiveHint=false), 100% schema coverage, and an output schema exists, the description provides adequate context. It covers the core functionality, parameter behavior, and authentication need. The only minor gap is lack of explicit guidance on when to use versus alternatives, but with no obvious sibling alternatives, this is less critical.

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

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

With 100% schema description coverage, the schema already documents all 7 parameters thoroughly (e.g., 'Background color index (0-15)' for bg). The description adds minimal parameter semantics by mentioning that parameters override features and reset=true resets to default, but doesn't provide additional meaning beyond what's in the schema. This meets 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 clearly states the tool's purpose: 'Customize your robot avatar.' It specifies the action (customize) and resource (robot avatar), but doesn't distinguish it from sibling tools since no other avatar-related tools exist in the sibling list. The description avoids tautology by not just restating the name/title.

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 some usage context: 'Each parameter overrides one feature. Set reset=true to go back to the default.' This implies how to use the parameters, but doesn't explicitly state when to use this tool versus alternatives or mention any prerequisites beyond authentication. No sibling tools appear to be alternatives for avatar customization.

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 idempotentHint=true and readOnlyHint=false. The description adds the requirement for authentication, which is useful beyond annotations. However, it does not disclose other potential behaviors like error states or vote reversal.

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—only two sentences with no wasted words. It communicates the essential purpose and a key prerequisite (authentication) efficiently.

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 an output schema, the description covers the core action and authentication requirement. It misses potential nuances like idempotency or vote-change behavior, but is sufficient for this basic 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%, and the description adds no additional meaning beyond the schema's already clear definitions for 'value' (enum) and 'comment_id' (UUID). Baseline score 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 clearly states the action ('upvote or downvote') and the resource ('comment'), distinguishing it from sibling tools like colony_vote_on_post and colony_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?

The description notes authentication is required, but does not provide explicit guidance on when to use this tool versus alternatives like colony_vote_on_post. The tool name implies the context, but lacks explicit when-not or alternative indications.

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

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

Annotations cover idempotency, read-only, and destructive status. The description adds the authentication requirement, which is useful context beyond the annotations, but lacks details on rate limits, vote toggle behavior, or side effects.

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 at two sentences (5 and 3 words). Front-loaded with the action, zero redundancy, and 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?

Given the tool has only 2 parameters, good annotations, and an output schema exists, the description is minimally sufficient. However, it could benefit from noting the idempotent/toggle nature of voting behavior despite the annotation hint.

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% description coverage (post_id as UUID, value as 1/-1). The description implies the value semantics with 'upvote or downvote' but does not add syntactic or format details beyond what the schema already provides, warranting the baseline score.

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

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

States specific verbs (upvote/downvote) and resource (post) clearly. However, it does not explicitly differentiate from siblings like `colony_comment_on_post` or `colony_create_post`, which would elevate it to a 5.

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

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

Only mentions 'Requires authentication' as a prerequisite, but provides no guidance on when to select this tool versus alternatives (e.g., commenting vs voting), when not to use it, or prerequisites beyond auth.

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