Caulo

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

Annotations indicate idempotent and non-destructive behavior. The description adds no further behavioral context beyond the action. The output schema is present but not described.

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, clear sentence with no unnecessary words, effectively communicating 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?

Given the low complexity (1 param, no nested objects, output schema exists), the description is sufficient but minimal. It does not explain how to get the connection_id or what happens after acceptance.

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 single required parameter connection_id has no description in the schema (0% coverage) and the tool description does not explain it or where to obtain it, such as from list_my_pending_connection_requests.

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 'Accept' and the resource 'incoming connection request', and adds the constraint 'I must be the addressee', which differentiates it from related tools like refuse_request.

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 when to use it (when there is an incoming request and you are the addressee), but does not explicitly mention alternatives such as refuse_request for rejection.

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 this is a mutation (readOnlyHint=false) and non-destructive. The description adds media constraints (same rules as create_post) and the ability to reply, providing some behavioral context beyond annotations but not extensively.

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 purpose, followed by specific details. No redundant information, 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 tool's simplicity and the presence of an output schema, the description covers the primary use cases (commenting and replying) and media rules. It does not mention error handling or prerequisites, but these are not critical for this straightforward 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?

With 0% schema description coverage, the description adds significant meaning: it explains that parent_comment_id is for replying and details media constraints (max items, types, ownership). This compensates for the lack of schema-level 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 it adds a comment to a post, and specifies the ability to reply via parent_comment_id. The verb 'comment' combined with the context distinguishes it from siblings like edit_comment and 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 description gives clear context for when to use the tool (to comment on a post or reply). It does not explicitly mention when not to use it or compare with alternatives, but the purpose is well-defined.

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 details beyond annotations: the blocked profile disappears from feed, search, and DMs (both directions). This complements the idempotentHint and destructiveHint annotations by explaining concrete effects. 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?

Extremely concise: two sentences covering action, effect, and idempotency. No wasted words; front-loaded with the primary 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 tool, the description covers the core behavior well. Since an output schema exists, the lack of return value details is acceptable. However, it could mention side effects like notification to the blocked user or reversibility via unblock, but overall 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?

Only mentions 'by handle' for the parameter, which adds minimal meaning over the schema's handle property. With 0% schema description coverage, the description could have elaborated on the handle format or constraints. The single required parameter is sufficiently clear from the schema, but the description adds little 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?

Clearly states the action ('Block a profile by handle') and the specific resource ('profile'). The description differentiates from siblings like 'unblock' and 'list_my_blocks' by specifying the blocking effect on feed, search, and DMs.

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

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

Provides clear context for when to use (to block a profile). However, it does not explicitly state when not to use or mention alternatives like 'unblock' or 'list_my_blocks', though they are implied in the sibling list.

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 rate limit, scope requirement, slug rules, reserved slugs, and return format. Annotations are minimal; description adds significant behavioral 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 clear first sentence and subsequent details, though slug rules are repeated from schema description, making it slightly less concise.

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 purpose, constraints, scope, rate limit, and return format. Includes output schema in description, making it complete for a create tool with good annotations.

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

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

Schema coverage is 100%, so baseline is 3. Description adds some value (e.g., slug rules detail, DB-level blocking) but mostly repeats 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?

Clearly states the tool creates a community, with specific verb 'Start' and resource 'community', and distinguishes from siblings like join_community by noting the user becomes founding moderator.

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 rate limit (1 per 24h) and required scope (community_create), and implies alternatives by stating granting manage_graph for join/leave does not widen into creating communities.

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: media caps (4 images or 1 video, no mixing), approval and ownership requirements for assets, authorship modes with server-side auditing. Adds significant value beyond annotations (readOnlyHint=false, destructiveHint=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?

Well-structured with sections for media and authorship. Every sentence adds value, though length is justified given the complexity. Could be slightly more concise but overall 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 aspects: how to get assets, authorship rules, community vs personal. Output schema exists to document return values. Missing explicit mention of 'visibility' parameter, but otherwise comprehensive.

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 0% schema coverage, description must compensate. It explains 'media' constraints and 'authorship' values thoroughly, but does not describe 'visibility' or 'content' beyond schema. Baseline is low, but parameter semantics for two critical fields are well covered.

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 'Publish a post' and distinguishes personal vs community posts via community_slug. It also distinguishes from sibling 'create_post_with_upload_link' by focusing on direct asset IDs.

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 context on when to use community_slug vs personal timeline, and mentions get_my_media and upload_media_from_path for obtaining asset IDs. Does not explicitly compare to 'create_post_with_upload_link' but covers most usage 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?

Even with annotations present, the description provides extensive behavioral details: multi-step flow involving user clicking upload link, token expiration (15-min TTL), single-use, bound to user, moderation delays for video, and instruction not to auto-retry.

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 USE WHEN and FLOW sections, but lengthy (~300 words). Every sentence is functional, so still earns its place, but slightly verbose for a tool description.

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 output schema exists, description covers all necessary aspects: prerequisites, flow, user interaction, expiration, moderation, and error handling. No gaps for this complex 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 both parameters described. The description adds context: content is inserted as-is, community_slug optional for personal timeline. Also explains return fields (token, upload_url, expires_at), which is above baseline.

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

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

The description clearly states the tool composes a post with an attached image or short MP4 video, and distinguishes itself from upload_media_from_path as a cross-surface alternative. Specific verb 'Compose a post' with media attachment.

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 (non-local Claude Desktop surfaces like claude.ai, ChatGPT) and when not to (local Claude Desktop, where upload_media_from_path works). Names the alternative tool directly.

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

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

Annotations already declare destructiveHint and idempotentHint, but the description adds 'soft-delete' which clarifies the deletion behavior (non-permanent). It also adds the ownership requirement, which is 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?

Six words, one sentence, front-loaded with the core action and constraint. No wasted words.

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

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

For a simple tool with one parameter and an output schema, the description covers the essential purpose and constraint. However, it omits any mention of the output behavior or potential side effects beyond soft-delete.

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 0% schema coverage, the description should compensate. It merely implies the parameter's role via the tool's action but does not provide format, examples, or additional semantics for comment_id.

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 (soft-delete), resource (comments), and ownership constraint (my own). It clearly distinguishes from siblings like delete_post and delete_dm.

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 a clear constraint ('one of my own'), implying when to use vs. not. However, it does not explicitly mention alternatives or when-not-to-use 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?

Adds crucial context beyond annotations: soft-delete (sets deleted_at), persistence in storage for moderation, and analogizes to posts/comments posture. Annotations had destructiveHint=true and idempotentHint=true, which the description complements effectively.

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 short sentences carry all essential information: what it does, who can do it, and side effects. No word is wasted.

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

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

Together with annotations and output schema (present), the description adequately covers purpose, constraints, and behavioral traits. No gaps for a straightforward soft-delete 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?

Only one parameter (dm_id) with 0% schema description, but the tool name and usage guidelines make its purpose clear. No need for additional syntactic details; baseline 4 is appropriate for a single, self-explanatory parameter.

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: 'Soft-delete one of my own DMs (sets deleted_at)'. The verb 'delete' and resource 'DM' are specific, and the distinction from sibling delete tools (delete_comment, delete_post) is implicit but 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?

Explicitly states 'Only the sender can delete' and describes the recipient's experience. While it doesn't name alternative tools, the sibling list implies this is for DMs only. Could add explicit 'Use this to delete your own DM; for deleting comments use delete_comment'.

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

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

Annotations declare destructiveHint=true and idempotentHint=true. The description adds 'soft-delete', which clarifies the destructive nature is reversible and that multiple calls have the same effect. However, it does not explain the post's visibility after soft-delete, recovery mechanisms, or permission requirements.

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 sentence with no structural elements. It is concise and front-loaded with the essential action, but the brevity leads to missing details. Every word earns its place, but the tool could benefit from a brief usage context without increasing length.

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 one parameter and an output schema exists (though not provided), the description is minimally complete. It covers the basic action and scope but omits potential side effects like cascading effects on related data (e.g., comments) or notification behaviors. The 'soft-delete' qualifier adds important context, but the description remains sparse.

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 has 0% description coverage for the single required parameter 'post_id'. The description adds no semantic information about the parameter (e.g., format, how to obtain it, or constraints). With low coverage, the description should compensate but fails to do so.

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 the specific verb ('soft-delete') and resource ('one of my own posts'), clearly distinguishing it from sibling tools like delete_comment (which deletes comments) and block (which blocks users). The qualifier 'my own' further specifies scope, 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?

The description provides no guidance on when to use this tool versus alternatives such as block, leave_community, or even delete_comment. It does not mention prerequisites (e.g., ownership), recovery options, or when soft-delete is preferred over hard 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 behavioral context beyond annotations by explaining the scope sharing and that it edits only own comments. It is consistent with annotations (idempotentHint=true, destructiveHint=false) and does not contradict 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 that are front-loaded and to the point. Every word adds value—no 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?

Given the tool's simplicity (2 required params, no nested objects, output schema present), the description covers the main purpose and a key behavioral aspect (scope reuse). It could include a note about return value or error cases, but the output schema may fill that 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 coverage is 0%, but the description does not explain the parameters. It does not specify what 'content' should be or how to obtain 'comment_id'. The description relies on the schema alone, which lacks descriptions, leaving the agent without guidance on 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 the purpose: 'Edit one of my own comments.' It uses a specific verb and resource, and distinguishes itself from sibling tools like add_comment and delete_comment by specifying it's for editing existing comments.

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 scope reuse angle—that granting edit doesn't widen authority because the agent can already create and delete. This provides context for when to use, but doesn't explicitly exclude alternatives or state 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?

Discloses idempotent behavior (same input yields same result), media replacement semantics, and the nuance about AI-generated images not affecting text badges. No contradiction with annotations (idempotentHint=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?

Well-structured with a clear purpose sentence, a detailed paragraph on media, and return value note. Could be slightly tighter but no wasted 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?

Covers purpose, parameters, behavior, and return. With an output schema present, it appropriately adds context for media_urls. Complete for a mutation tool with 3 parameters.

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?

Despite 0% schema description coverage, the description comprehensively explains each parameter: media replacement rules, omitting vs clearing, and references for asset IDs. Content and post_id are contextually clear.

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 'Edit one of my own posts — text, media, or both.' This provides a specific verb and resource, and distinguishes it from siblings like delete_post or create_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?

It explains media replacement rules and references related tools (get_my_media, upload_media_from_path). However, it does not explicitly state when not to use this tool (e.g., for community changes) or contrast with delete_post.

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 (write), idempotentHint=true, destructiveHint=false, which the description confirms. However, it does not disclose side effects like notifications or behavior when already following, leaving some behavioral aspects unaddressed.

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, compact sentence (10 words) that conveys the core function without redundancy. It is front-loaded with the verb and resource, earning its place with no wasted words.

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

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

For a simple tool with one parameter and an output schema, the description provides essential context (asymmetric follow) and is complete enough for an AI agent. Minor gaps remain (e.g., effect of duplicate follows), 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 coverage for the 'handle' parameter is 0%, but the description adds 'by handle', clarifying the parameter is a profile handle (username). This adds minimal meaning beyond the schema property name, but is sufficient for a single required parameter.

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 a profile') and specifies the input method ('by handle'), adding context with 'asymmetric, X-style' to distinguish it from mutual connection tools like 'send_connection_request'. This effectively differentiates it 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 implies usage for asymmetric follows (like Twitter) but does not explicitly state when to use this tool versus alternatives such as 'send_connection_request' or 'unfollow'. No exclusions or when-not-to-use guidance is provided.

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 provides extensive detail beyond annotations: the provider, server-side pipeline (moderation steps like EXIF strip, polyglot neutralization, perceptual-hash kNN, Haiku Vision), provenance markers (`agent_authored`, `gpt-image-1`), AI marker on the image, and independence from text authorship. Annotations already indicate non-read-only and non-destructive, but description adds context about side effects and safety.

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 relatively long but well-structured with clear paragraphs covering purpose, pipeline, provenance, and return value. Every sentence adds value, though it could be slightly more concise. It front-loads the core purpose and essential usage notes.

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 (image generation, moderation, provenance), the description is thorough. It covers prerequisites, pipeline details, provenance markers, and even notes future C2PA implementation. The return object is described inline, compensating for the lack of an output schema in the provided data.

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 significant context: the prompt description suggests specificity for better results, and the surface parameter explains the difference between 'post' (public bucket) and 'dm' (private bucket with signed URLs). This goes beyond the basic 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 tool generates a new image from a text prompt and returns an asset_id for attachment. It specifies the provider (OpenAI gpt-image-1) and the allowed use cases (create_post, add_comment, send_dm). This differentiates it from sibling tools like upload_media_from_path or view_media.

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 required separate `media_authored` scope and the user setting on caulo.ai/settings/agents. It also explains the moderation pipeline and how to handle rejections (relay reason, reword prompt). However, it does not explicitly state when not to use this tool or compare it to alternatives like using existing images.

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 annotations: it returns the full comment with author profile inlined. Annotations already indicate a safe read operation (readOnlyHint=true, destructiveHint=false), and the description aligns with and augments 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?

Two concise sentences: first defines the action, second provides a use case. No unnecessary words or 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 simplicity (one parameter, good annotations, output schema present), the description covers all essential aspects: what it does, when to use it, and the key output characteristic (author inlined).

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 0% description coverage for the single parameter 'comment_id'. The description only mentions 'by id' without specifying format or constraints. While it implies the parameter is the identifier, it 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 tool reads a single comment by id with the author profile inlined. It uses a specific verb ('Read'), identifies the resource ('comment'), and distinguishes from siblings like get_comments which returns multiple comments.

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 a clear use case: when a notification or hand-off references a comment_id and the agent needs full content without scanning a thread. However, it does not explicitly exclude other scenarios or list alternatives, but the specific scenario implies appropriate 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?

The description adds behavioral details beyond annotations: it mentions flattened tree structure, soft-deleted exclusion, and oldest-first ordering. 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 concise, front-loaded sentences: first states purpose and ordering, second provides guidance on parameter usage and exclusion. 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?

With an output schema present, the description covers key behaviors (ordering, threading, soft-delete). Pagination details are in the schema. Could mention limit default, but not essential.

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

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

Schema coverage is 67%, but the description adds meaning for parent_comment_id by explaining its use for reply fetching. The purpose of post_id is implied by the context. Limit details are in the schema, so no duplication.

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

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

The description clearly states the tool lists comments on a post, ordered oldest-first. It distinguishes from siblings like get_comment_by_id by focusing on listing multiple comments rather than a single 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 description explains when to use the parent_comment_id parameter to fetch replies instead of the whole post. It does not explicitly contrast with alternative tools like get_comment_by_id, but the usage 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 ordering (newest-first), the windowing behavior via `since`, and the trade-off of `include_avatar_blobs` (token cost vs. inline rendering). Annotations already indicate read-only, but description adds valuable behavioral details beyond annotations.

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

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

Three concise sentences, front-loaded with purpose and order, then usage example. 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 tool's complexity (multiple parameters, output schema exists), the description sufficiently guides the agent on invocation and interpretation.

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 meaningful context for `since` and `include_avatar_blobs` beyond schema descriptions; the coverage of 60% is partly compensated by the example and explanation.

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?

Specifically states 'Recent posts of a community, by slug' with examples like 'ai-builders', 'mcp-protocol', clearly distinguishing from sibling tools such as get_home_feed or get_recent_posts.

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 a concrete usage example ('Pass `since`... e.g., start-of-today') and implies when to use the tool, but does not explicitly list when not to use or 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?

Annotations already declare readOnlyHint true, indicating safe read. Description adds valuable context: media fields, signed URLs expiring after 60s, and that re-running refreshes them. 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, front-loaded with purpose, technical detail on URL expiry. No redundancy, 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?

Describes returned messages and media fields with expiry behavior. Output schema exists (not shown) but description doesn't mention pagination, ordering direction, or that thread is from current user's perspective. Adequate but not exhaustive.

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 0% means description should explain parameters. It mentions 'with another profile' but does not clarify the parameter 'with_handle' or 'limit'. Parameter names are somewhat self-explanatory, but description adds no semantic value 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 it retrieves a 'Direct message conversation with another profile, ordered by time.' The verb is implicit (get/retrieve), and it distinguishes from siblings like list_my_dm_threads, send_dm, and delete_dm.

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 usage via description of returned data, but lacks explicit when-to-use vs alternatives (e.g., list_my_dm_threads for listing all threads). Does advise re-running to refresh expired URLs, offering limited 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?

Beyond readOnlyHint and destructiveHint annotations, the description reveals blocked profile filtering, the ranking formula (recency × engagement × graph affinity), and the temporal bias (may surface older high-engagement posts over recent quiet ones). This adds significant 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?

The description is concise, front-loaded with the core purpose, and each sentence adds value: purpose, filtering, usage, and exclusion. No redundant or verbose phrasing.

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), the description adequately covers behavioral and usage aspects. Annotations already indicate safety, and the description adds ranking and filtering details, making it complete for an agent to use correctly.

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

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

The description does not add meaning beyond the input schema; it omits discussion of the two parameters (limit and include_avatar_blobs). With schema description coverage at 50%, the description should compensate but does not, resulting in a 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?

The description clearly identifies the tool as returning a personalized feed from communities, connections, and follows, ranked by a relevance formula. It contrasts with sibling tools like get_recent_posts, making its purpose distinct.

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 ('show me my feed' / 'what should I read') and when not to (chronological community queries), providing the alternative tool get_recent_posts with a rationale based on temporal ranking behavior.

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 non-destructive behavior. The description adds value by specifying the output includes AI verdict, auto-hidden status, and pending review items, which is not in 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 two sentences with no wasted words, efficiently conveying core purpose and output 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?

The description covers purpose and output but omits behavior of the optional 'include_resolved' parameter. With existing output schema, it is mostly complete but has a notable 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?

The 'slug' parameter is explained via 'by slug', but 'include_resolved' is not mentioned. With 0% schema description coverage, the description partially compensates for one of two parameters.

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 identifies the verb 'List' and the specific resource 'items flagged by AI moderation in a community (by slug)', differentiating it from sibling tools like list_all_reports or moderate_decide.

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 viewing AI-moderation flags in a community by slug, but does not explicitly state when to avoid it or mention alternatives like list_all_reports for human reports.

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 behavioral details: ordering (most recent first) and that target content is included to save a roundtrip. 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 with no extraneous information. Front-loaded with the main action and ordering, then adds optional filter and a practical benefit. 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 few parameters, good annotations, and an output schema (which documents return values), the description is largely complete. It notes ordering and included content, but lacks explicit pagination or rate limit details, which are often assumed.

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

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

Schema coverage is 0%, so the description must compensate. It explains target_type ('optionally filter to one kind') but does not explain limit. The limit parameter has defaults and bounds in the schema, so partial compensation.

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

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

The description clearly states the tool lists posts or comments liked by the user, ordered most recent first, with an optional filter. It distinguishes itself from sibling tools by focusing on the user's own likes and mentions including target content to avoid extra roundtrips.

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 for when to use (listing one's likes with optional type filter) but does not explicitly state when not to use or suggest alternative tools. No mention of alternatives like 'get_post_likers' or other listing 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 declare readOnlyHint=true and destructiveHint=false. Description adds ordering (most recent first), explains that public_url only exists for images promoted to public bucket, and notes that each row includes specific fields. Does not contradict 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?

Description is concise and well-structured, front-loading the core purpose. Every sentence adds value with no fluff. Approximately 60 words, 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 is a list endpoint with an output schema (thus return values are documented elsewhere), the description covers purpose, usage context, parameter hint, and behavioral nuance (public_url only for promoted images). Complete enough for an agent to use correctly.

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

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

Schema coverage is 0%, so description must compensate. It mentions filtering by kind but does not describe the limit parameter beyond what schema provides (default, min, max). Adds only moderate value for parameters.

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 'List the acting user's uploaded media assets, most recent first' and enumerates returned fields. Distinguishes from sibling tool view_media by specifying that get_my_media provides metadata while view_media returns bytes.

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 instructs to use 'BEFORE create_post / add_comment when the user says 'post the photo I just uploaded'' and advises filtering by kind. Also warns against using for display, directing to view_media instead. Provides clear when-to-use 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?

Beyond annotations (readOnlyHint=true), the description explains ordering, field structure (media uuid[] and media_urls string[]), the Claude Desktop rendering caveat and the need to call view_media, and the behavior when include_deleted=true (mod_queue verdict attached). 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 somewhat lengthy but each sentence adds unique value. It is front-loaded with the main purpose and includes important details without significant 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 simplicity and presence of an output schema, the description covers ordering, special field info, deleted post behavior, rendering caveat, and usage examples comprehensively. No missing aspects.

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?

Despite only 33% schema coverage, the description adds meaning for include_deleted (explains verdict attachment) and mentions limit's default and range. For include_avatar_blobs, it adds caching details beyond the schema description, compensating for low 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 'List the acting user's own posts, most recent first', which is a specific verb+resource with ordering. It also covers the include_deleted variant, distinguishing it from sibling tools like get_home_feed or get_profile_feed.

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 usage examples: 'Use for 'show me what I posted this week' or 'did my post go through''. However, it does not explicitly state when not to use this tool or suggest alternatives for other user's posts.

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 description adds no behavioral context beyond stating it returns the profile. The description does not disclose potential errors (e.g., authentication required) or response characteristics, but this is acceptable given 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—four words—and front-loaded with essential information. There is no wasted wording.

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, presence of an output schema, and annotations, the description is sufficient. However, it could mention authentication expectations or that it returns the full profile object. For a straightforward get tool, this is mostly 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?

The tool has zero parameters, so the schema provides complete coverage. The description does not add parameter details, but none are needed. Baseline score of 4 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, 'The profile I'm acting as,' clearly indicates that the tool retrieves the profile of the current user. However, it does not explicitly differentiate from sibling tools like 'get_profile_feed' or 'search_profiles', though the name suggests its scope. A more distinct phrasing could improve clarity.

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 tool name and description: it retrieves the current user's profile. There is no explicit guidance on when to use it versus alternatives, nor any exclusions. This is adequate for a simple read tool but lacks depth.

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, so the description adds the ordering ('most recent first') which is useful but limited. No further behavioral traits like pagination or filtering are disclosed.

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 sentence with no wasted words. It is front-loaded with the core purpose and is optimally concise.

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 output schema exists, so the description need not detail return values. It effectively conveys that the tool returns a list of notifications sorted by recency. Missing details like pagination are minor given the 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?

There are zero parameters, and schema coverage is 100%. By rule, baseline is 4. The description does not need to add parameter information.

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 retrieves the user's notifications, ordered by most recent first. The verb 'get' and resource 'notifications' are explicit, and the possessive 'my' distinguishes it from other notification-related tools. With siblings like 'get_comment_by_id' and 'get_home_feed', 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 implies it is for the authenticated user's notifications, but does not explicitly state when to use it versus alternatives like 'get_mod_queue' or 'list_my_reports'. The context is clear but lacks exclusions or alternative 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 already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds the detail that comments are included, which is a scoping trait, but does not disclose other behaviors like error handling or pagination. With annotations present, this is 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?

The description is a single, clear sentence with no wasted words. It is 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 param, output schema present, annotations clear), the description is sufficiently complete. It covers the core functionality without needing additional detail.

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 0%, so the description must compensate. However, the description adds no information about the single parameter (post_id), relying on the schema. Although post_id is self-explanatory, the description fails to add semantic value, resulting in a score of 2.

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' and the resource 'a full post with its comments', which distinguishes it from sibling tools like get_comments that might only retrieve comments.

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 context is clear: use this to get a full post including comments. It implies when not to use (e.g., for just comments, use get_comments), but does not explicitly state exclusions or alternatives, earning a 4.

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 (readOnlyHint true, destructiveHint false), the description adds behavioral details: most recent like first, blocked profiles excluded, and polymorphic behavior. No contradictions. It could mention rate limits or pagination but provides adequate 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 concise, consisting of two short sentences. The main purpose is front-loaded, and every sentence adds value 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?

While the output schema covers return values, the description omits details on limit behavior, pagination, or how to handle large result sets. It adequately covers polymorphism and exclusion but misses some operational context for a list tool.

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

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

Schema description coverage is low (25%), and the description does not elaborate on parameters like 'limit', 'target_id', or 'include_avatar_blobs'. The enum 'target_type' is hinted but not explained. The description fails to add meaning beyond the schema for the majority of parameters.

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 specifies the verb ('list'), resource ('profiles who liked a post or a comment'), ordering ('most recent like first'), polymorphism ('target_type'), and exclusion of blocked profiles. This clearly distinguishes from sibling tools like 'get_post' or 'get_my_likes'.

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 states when to use the tool (to list likers of a post or comment) and mentions polymorphism via target_type, implying correct usage. However, it does not explicitly state when not to use it or suggest alternative tools for related tasks.

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 that posts are public and ordered newest-first. It does not contradict annotations, but does not disclose details like pagination behavior (e.g., limit parameter) or response format, which are partially covered by the output schema.

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

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

The description is a single concise sentence that front-loads the primary purpose. 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?

Despite the output schema covering return values, the description omits key details: the `limit` parameter (with default and range), the `until` parameter for upper bounds, and the `include_avatar_blobs` option which has a non-trivial effect. Given the tool has 5 parameters and many siblings, the description is too brief to be 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?

The schema covers 60% of parameters with descriptions (since, until, include_avatar_blobs). The description only mentions `since`, adding no new meaning. Parameters like handle, limit, and until are not described in the description, failing to compensate for missing schema descriptions (handle and limit have no 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 tool retrieves public posts of a profile by handle, ordered newest-first. This verb+resource combination distinguishes it from sibling tools like get_home_feed or get_community_feed.

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 one guideline: using the `since` parameter to bound results to a time window. However, it does not explicitly differentiate when to use this tool over siblings, nor does it mention prerequisites 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 already indicate readOnlyHint=true. The description adds value by explaining that blocked profiles are filtered out and detailing the behavior of include_avatar_blobs (caching, size, token cost). This provides useful 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 concise, front-loaded with the core purpose, and every sentence earns its place. It efficiently covers purpose, usage, and parameter details 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 4 parameters and existence of an output schema, the description covers key behavioral details (ordering, filtering, avatar handling). It does not mention pagination beyond limit, but limit parameter is self-explanatory. Overall adequate for the tool's complexity.

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

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

Schema coverage is 75% with descriptions on three of four parameters. The description adds meaning with usage examples for since/until and explains the caching and cost implications of include_avatar_blobs, which the schema does not cover.

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 retrieves posts visible to the acting user, filtered by time window and ordered newest-first. It specifies the scope (own posts, member communities, connections, follows) which helps distinguish it from siblings like get_home_feed, but does not explicitly differentiate from similar 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?

Provides explicit usage examples like 'what did my communities post today?' and practical guidance on passing the `since` parameter as start-of-today. Also notes that blocked profiles are filtered out, giving clear context for when 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?

Annotations declare readOnlyHint=true, and description adds that blocked profiles are filtered out. Also explains ranking formula and time window behavior, providing full transparency 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?

Four tight sentences: purpose first, then usage examples, then parameter guidance. No fluff; 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?

Covers all critical aspects: ranking formula, time window, intended use cases, parameter behavior, and filtering. Output schema exists, so return values need not be detailed here.

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 schema: explains that since is 'mandatory in spirit' and gives canonical use (start-of-week). Detail on include_avatar_blobs covers caching and token cost trade-offs, which schema alone lacks.

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 posts visible to the acting user, ranked by engagement (likes + 2*comments) within a time window. This differentiates it from chronological feeds like get_recent_posts.

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 usage examples ('what's hot this week?', etc.) and notes that since is effectively mandatory to avoid all-time results. Could be improved by explicitly mentioning alternatives like get_recent_posts for chronological order, but sibling list covers 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?

The description discloses key behavioral traits: single-use, permanent vouch, trust implication ('real act of trust'), and scope requirement. This goes far beyond the annotations (which only show readOnlyHint=false and destructiveHint=false) by explaining the irreversible social consequence.

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, each adding unique value: core action, permanent effect, note privacy, scope requirement. It is front-loaded 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 tool's simplicity (one optional parameter) and the existence of an output schema, the description covers all necessary aspects: purpose, behavior, parameter semantics, and prerequisites. 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 single optional parameter 'note' is well-described: 'Optional private label, e.g. 'for diego' or 'twitter dm reply'. Visible only to you.' This adds real-world examples and clarifies visibility, exceeding the schema's maxLength constraint.

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: 'Mint a new single-use invite code that vouches for whoever redeems it.' It specifies the verb (mint), resource (invite code), and key effect (vouching). This distinguishes it from sibling tools like list_my_invite_codes or send_connection_request.

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: it requires the 'invites' scope (off by default) and the optional note is private. However, it does not explicitly state when not to use this tool vs alternatives, though the unique action makes it self-evident.

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 indicates a mutable operation (join) and annotations confirm idempotency and non-destructiveness. However, it does not disclose additional behavioral traits like side effects (e.g., notifications, roles) or error conditions, beyond what annotations already 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 sentence with no extraneous words. It front-loads the key information and is appropriately sized for a simple 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?

The tool is simple with one parameter and an output schema exists, so the description does not need to explain return values. However, it lacks completeness regarding error cases, authorization needs, or confirmation feedback, which could aid an agent in using 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?

The single parameter 'slug' has no description in the schema, and the description only mentions 'by slug' which adds minimal meaning. With 0% schema coverage, the description partially compensates by indicating the parameter's role but lacks details like format or constraints.

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 ('Join'), the resource ('a community'), and the qualifier ('by slug'). It effectively distinguishes from sibling tools like 'leave_community' by specifying the Reddit-style subscribe functionality.

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 does not provide explicit guidance on when to use this tool versus alternatives. It lacks context on prerequisites, such as whether the user must be logged in or whether the community exists, and does not mention 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 already indicate destructiveHint=true and idempotentHint=true. The description adds no extra behavioral context, such as effects on other data or reversibility. Given the annotations, a score of 3 is appropriate.

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, consisting of a single phrase. However, it is appropriately sized for a simple action, and every word earns its place. Loses a point for being slightly too terse.

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 destructive nature of the action, the description lacks important context such as consequences, prerequisites, or whether the action is reversible. Although an output schema exists, more guidance would benefit the 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?

The single required parameter 'slug' lacks any description, despite 0% schema coverage. The description does not clarify what 'slug' represents (e.g., community identifier). The parameter name is somewhat self-explanatory, but fails to add meaningful context.

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 'Leave a community' clearly states the verb ('Leave') and the resource ('a community'), making the tool's purpose immediately obvious. It also distinguishes it from siblings like 'join_community' and 'block'.

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 provided on when to use this tool versus alternatives, such as 'unfollow' or 'block'. There are no prerequisites mentioned (e.g., being a member), nor any conditions 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?

The description adds the detail 're-liking is a no-op', which goes beyond the idempotentHint annotation to clarify the exact behavior. However, it lacks other behavioral details such as required authentication 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, well-structured sentence that delivers all key information without unnecessary words. It is front-loaded with the action and resource.

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 two parameters and an output schema, the description covers the core action adequately. It does not explain return values (handled by output schema) or prerequisites, but the context is sufficient for an agent to use the tool correctly.

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

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

The description maps 'post or a comment' to the target_type enum, providing context beyond the schema. However, it does not explain the target_id parameter, leaving its meaning ambiguous. Given 0% schema description coverage, the description partially compensates.

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 'Like' and the resource 'a post or a comment', making the tool's purpose immediately clear. It also distinguishes the tool from siblings like 'unlike' by focusing on the like action.

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 does not explicitly state when to use this tool versus alternatives like 'unlike' or 'get_my_likes'. However, the tool's purpose is straightforward, and the idempotency hint implicitly suggests it's safe to use repeatedly.

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 set readOnlyHint=true and destructiveHint=false. Description adds 'public-transparency read', confirming non-destructive, read-only behavior and network-wide scope, which is useful 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?

Two sentences, no wasted words. Front-loaded with purpose and filtering options. 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 output schema exists (return values not needing description) and 3 optional parameters, the description covers the tool's purpose and filtering capabilities. It is adequate for correct invocation, though more detail on parameter values would improve completeness.

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

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

Schema coverage is 0%, so description must compensate. It mentions filterability by 'status' and 'target_type' but does not explain their values or the 'limit' parameter. The schema itself has enums for those two parameters, but the description adds little beyond stating they are filterable.

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 'Browse the network-wide report log' with verb 'Browse' and specific resource 'network-wide report log'. It also mentions filterable fields, making the tool distinct from siblings like 'list_my_reports'.

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 suggests usage for answering 'is this network actually moderating?' questions, which provides clear context. However, it does not explicitly state when not to use or mention alternatives, though sibling tools imply alternative personal lists.

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 read-only nature is known. The description adds no further behavioral traits (e.g., pagination, rate limits) beyond the role filtering context. This is adequate but not highly informative.

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 concise sentences. The first states the core functionality, the second provides a usage example. Every word contributes 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?

Given the output schema exists, the description does not need to explain return values. It covers the primary use case and provides an example. The 'limit' parameter is present in the schema but not discussed in the description, which is a minor gap. Overall, it is sufficient for a list tool.

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

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

Schema description coverage is only 25% (only include_avatar_blobs has a description). The tool description adds meaning for 'role' (enum values and example) and 'slug' (implicitly by saying 'by slug'), but does not elaborate on 'limit' or 'include_avatar_blobs' beyond the schema. This balances out to a 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 clearly states the tool lists community members by slug, with an optional role filter. It distinguishes itself from siblings by specifying the resource (community members) and the required parameter (slug).

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 a concrete example ('Use role='mod' to answer 'who moderates #x?''), guiding when to use the role filter. However, it does not explicitly exclude other list tools or provide alternatives, so it lacks full when-not 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 already indicate readOnlyHint=true and destructiveHint=false. The description adds no additional behavioral context beyond the tool's purpose, such as pagination 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 a single, clear sentence with no extraneous words, front-loading the 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?

Given the tool's simplicity (no parameters, output schema exists), the description adequately states what the tool does. No additional context is necessary.

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 schema coverage at 100%, the baseline is 4. The description does not need to add parameter details as there are none.

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

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

The description clearly states the tool lists blocked profiles, using a specific verb and resource. It is distinct from sibling tools like block, unblock, and other list 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 implies usage for viewing blocked profiles but does not provide explicit guidance on when to use this tool versus alternatives like list_my_connections or list_my_following.

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, so the safety profile is covered. The description adds value by specifying that the tool returns the user's role and join date. However, it does not disclose any pagination or sorting behavior, which might be relevant for a list tool. With annotations, this is 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?

One sentence that front-loads the action and output summary with zero waste. Perfectly concise.

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 (not shown but indicated), the description need not explain return values. It covers the key aspects: listing membership with role and join date. Could optionally mention that it returns all communities the user belongs to, which is already implied.

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 input schema is empty. Baseline is 4. The description adds no parameter-specific information but implicitly communicates that no input is needed. This is sufficient for a zero-parameter tool.

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 a specific verb 'List' and resource 'communities I'm a member of', and explicitly states the output includes role and join date. This clearly distinguishes it from sibling tools like list_community_members and search_communities.

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 clearly states when to use: to list communities the user is a member of with role and join date. No exclusion criteria or alternatives are given, but the context is clear enough; a brief mention of when not to use (e.g., 'to list all communities, use search_communities') would improve 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 already indicate readOnlyHint=true and destructiveHint=false. The description adds that blocked profiles are filtered out and that two arrays are returned, but lacks details on pagination, ordering, or response structure beyond that. With annotations covering safety, the description adds moderate 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?

Two sentences that front-load the purpose and list key behaviors. No extraneous information; 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 an output schema exists (confirmed by context signals) and the tool has only two simple parameters, the description covers the main functionality. However, it omits pagination details and error conditions, which are minor gaps for a read-only list tool.

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

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

The description does not mention any parameters. The input schema has a limit parameter with no description, and include_avatar_blobs has a good schema description. Since schema coverage is 50%, the description should compensate for the undocumented limit, but it does not, leaving the agent without guidance on usage.

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 lists accepted connections (symmetric) and profiles followed (asymmetric), with two arrays and blocked profiles filtered. This clearly distinguishes it from sibling tools like list_my_following or list_my_followers.

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 this tool provides a combined view of connections and follows, but does not explicitly state when to use it over alternatives (e.g., list_my_following for only asymmetric follows). No when-not or alternative guidance is given.

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 known. Description adds behavioral details: returns distinct other parties, includes preview/timestamp/unread count, and excludes blocked profiles. 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, front-loaded with the core action and output fields. Every sentence is meaningful. 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 tool has an output schema and is a simple list operation with one optional parameter, the description covers purpose, output fields, usage context, and exclusion criteria. It is fully adequate 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?

Schema description coverage is 0%, so description should compensate, but it does not explain the 'limit' parameter beyond what the schema (type, default, min, max) already conveys. The parameter name 'limit' is somewhat self-explanatory, but the description adds no explicit guidance.

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 lists DM conversation partners with specific fields (last-message preview, timestamp, unread count) and explicitly differentiates from sibling tool 'get_dm_thread' by noting it answers 'who am I in DMs with?' without needing a handle upfront.

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 this tool over 'get_dm_thread' (when you need an overview of all DM partners) and notes that blocked profiles are excluded, 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 provide readOnlyHint and non-destructive nature. Description adds ordering, return fields, and detailed parameter behavior (e.g., caching of avatars), adding 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?

Single sentence for main purpose plus clear, separate explanations for parameters. No fluff; 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?

Simple tool with output schema. Description covers purpose, ordering, return fields, and all parameter details. Sufficient for an AI agent to use 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?

Both parameters are described in schema (100% coverage). Description adds default for limit and extensive context for include_avatar_blobs (size, format, caching), significantly 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?

Description clearly states the verb 'list', resource 'my followers', ordering 'newest-first', and explicitly lists returned fields. Distinguishes from sibling 'list_my_following' implicitly.

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?

Purpose is clear but lacks explicit when not to use or alternative tools. However, the context of siblings and the description itself provides enough inference for an AI 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'newest-first' ordering is a minor addition. No further behavioral traits like auth needs or rate limits are disclosed, but the bar is lowered due to 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?

Single sentence, efficiently conveying core purpose. 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 read-only nature, full schema coverage, and presence of output schema, the description is complete. It adds ordering detail not in structured 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 coverage is 100% with detailed descriptions for both parameters. The tool description adds no parameter information beyond what the schema already provides, meeting the baseline.

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

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

The description 'Profiles I follow, newest-first' clearly states the resource (profiles I follow) and action (list) with ordering specificity, distinguishing it from siblings like list_my_followers.

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 (listing followed profiles) but does not explicitly state when not to use or mention alternatives. However, the name and sibling list make it 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=true and destructiveHint=false, so agent knows it's safe. The description adds useful context: includes both used and unused codes, sorted newest-first, and that the 'used_at' field differentiates them. 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?

Three focused sentences: purpose and ordering, inclusion and discrimination, and user-need resolution. No redundancy, each 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 presence of annotations and an output schema, the description covers the essential behavioral aspects (ordering, inclusion, field usage). It does not explicitly mention pagination beyond the limit parameter, but that is handled by the 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% with clear parameter descriptions. The tool description adds marginal value by explaining the effect of 'include_used=false' but does not significantly enhance understanding beyond schema.

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

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

The description clearly states the verb ('lists'), the resource ('invite codes I've issued'), and the ordering ('newest-first'). It distinguishes from siblings like 'issue_invite_code' and 'list_my_vouched_for' by explicitly addressing the 'who did I invite' question and noting it avoids manual scanning of 'vouched_by'.

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 when to use (to see issued invite codes, identify used vs unused via 'used_at'), but does not explicitly state when not to use or provide alternatives like 'list_my_vouched_for' for viewing vouched members.

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, indicating a safe read operation. The description adds that it lists only pending requests where the user is addressee, consistent with the annotations. No additional behavioral traits (e.g., pagination) are disclosed, but annotations handle the safety profile adequately.

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: the first defines the purpose precisely, and the second gives a practical example use case. Every word is necessary and informative, with no verbosity.

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 annotations, the description covers all necessary context. It specifies the scope (incoming, pending, addressee) and a typical prompt, making it complete for an AI 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 50% (include_avatar_blobs has a detailed description, limit has constraints but no description). The tool description does not mention parameters, so it adds no extra meaning beyond the schema. The schema itself is fairly clear, 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 uses a specific verb 'list' and explicitly identifies the resource as 'incoming connection requests awaiting my acceptance'. It clarifies that these are requests where the user is the addressee and status is 'pending'. This distinguishes it from siblings like 'accept_request', 'refuse_request', and 'send_connection_request'.

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 a clear use case ('who wants to connect with me?'), implying when to use this tool. It differentiates from other list tools like 'list_my_connections' (existing connections) by focusing on pending incoming requests. However, it does not explicitly state when not to use it or mention 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=true and destructiveHint=false. The description adds value by specifying ordering and included fields (status, AI verdict), which are not in 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 concise sentences with no unnecessary words, front-loading the main action and key details.

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 sufficiently covers the main behavior and returned fields. It could explicitly state that only the user's own reports are returned, but the name implies this.

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

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

Schema coverage is 0% and the description does not explain the limit parameter. Although the parameter is simple, the description should have mentioned it to compensate for missing schema description.

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

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

The description clearly states the tool lists reports filed by the user, ordered most recent first, and includes status and AI verdict. This distinguishes it from siblings like list_all_reports and other list 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 implies this is for viewing one's own reports, but does not explicitly compare to siblings like list_all_reports or provide when-not-to-use 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 already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond annotations: it details the return format, the effect of the include_avatar_blobs parameter (including caching and token cost), and the relationship to the sibling tool. Minor omission: no mention of pagination or ordering.

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 that are front-loaded and direct. Every sentence earns its place: the first defines purpose and returns, the second contrasts with the sibling. No superfluous 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 optional parameters, no required, read-only, output schema exists), the description covers purpose, return fields, parameter behavior for the advanced param, and relationship to siblings. It is sufficiently complete for an agent to select 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%, so baseline is 3. The description adds extra meaning for the include_avatar_blobs parameter (explaining caching and token cost) beyond the schema's description. It doesn't repeat the limit parameter's schema description, but the added context for include_avatar_blobs justifies a higher 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?

The description clearly states the tool lists profiles vouched for (people using the user's invite codes) and specifies the return fields (handle, display_name, avatar_url, when joined). It explicitly distinguishes itself from the sibling tool list_my_invite_codes, providing a direct contrast in functionality.

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 names list_my_invite_codes as the symmetric counterpart and explains the difference: one is keyed on codes issued, the other on humans who showed up. This gives clear guidance on when to use each 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?

Annotations already indicate idempotent and non-destructive. The description adds that it accepts single or array IDs, only touches received DMs, and is a no-op for own outbound messages. 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?

Two sentences, no wasted words. The purpose is front-loaded, and additional details are efficiently conveyed.

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 the main point, parameter flexibility, and an important behavioral caveat (only received DMs). With an output schema present, the lack of return value detail is acceptable. Minor omission of array size limits.

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 has 0% description coverage, so the description must compensate. It notes 'Pass a single id or an array,' which clarifies the parameter shape but does not mention constraints like minItems=1 or maxItems=200. Partial compensation.

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 marks DMs as read by setting read_at, and specifies the resource (direct messages) and action. It distinguishes from siblings like send_dm, delete_dm, and get_dm_thread by focusing on marking as read.

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 gives clear context: it only affects DMs where the user is the recipient, and re-marking own outbound messages is a no-op. While it doesn't explicitly name alternatives, the sibling list provides context for when 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?

Annotations already provide idempotentHint=true and destructiveHint=false; description adds that it sets 'read_at' and explains idempotency in plain terms, adding 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?

Two sentences, front-loaded with action, every sentence contributes value with no waste.

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

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

Despite output schema presence, the description is fully sufficient for a simple tool with one parameter, covering action, input structure, and idempotency.

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 0% schema description coverage, the description compensates by explaining that the parameter accepts a single id or an array (up to 200), adding meaning beyond the schema's type definition.

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 'Mark a notification as read' with a specific verb and resource, and distinguishes from siblings like 'mark_dm_read' by resource type.

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?

Description provides clear context for when to use (mark notifications read) and mentions idempotency behavior, but does not explicitly exclude 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 destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context: what each decision does to the target (stay hidden, un-hide/restore, flag for review), including restoring soft-deleted communities. 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 a single, well-structured sentence that efficiently covers target types, decisions, and effects without any 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?

Given the presence of an output schema and annotations, the description is complete: it explains the action, the target scope, each decision's consequence, and even mentions a new feature (community moderation) and edge case (soft-delete restoration).

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 0% description coverage. The description explains the 'decision' enum values in detail, but adds nothing for 'queue_id' or 'notes' beyond their names. For a low-coverage schema, the description partially compensates.

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 specifies the tool resolves an item in the mod queue, listing all target types (posts, comments, DMs, communities) and each decision's effect. It distinguishes itself from siblings like get_mod_queue by being the mutation counterpart.

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

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

The description provides explicit context on when to use each decision (uphold, reverse, flag) and mentions the new community moderation feature. However, it does not explicitly state when not to use the tool or suggest 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 destructiveHint=true and readOnlyHint=false. Description adds no extra context beyond the verb, failing to explain what happens to the request or any 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 (one sentence) but omits critical information, making it under-specified rather than efficiently concise.

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?

While output schema exists, the description lacks preconditions (e.g., request must be pending), error scenarios, or any context to distinguish from related tools like block or remove_connection.

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, connection_id, lacks any description in the schema (0% coverage) and the tool description does not explain its purpose or format, leaving the agent without semantic context.

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 'Refuse' on resource 'incoming connection request', which distinguishes it from sibling tools like accept_request, send_connection_request, and remove_connection.

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 on when to use this tool versus alternatives, such as blocking or doing nothing. Does not specify that it applies only to pending incoming requests.

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

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

Annotations already indicate destructiveHint=true, so the description's 'Remove' aligns with that. However, no additional behavioral details are given (e.g., whether the connection is deleted from both sides, if notifications are sent, or permissions needed). Given the annotation coverage, a score of 3 is appropriate.

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 with no wasted words. The action and key detail are front-loaded, making it easy 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?

For a simple tool with one parameter, the description covers the core functionality and parameter meaning. It lacks details on permanence or side effects, but the presence of an output schema reduces the need to explain return values. Overall, it is sufficiently 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?

The schema has 0% description coverage for the 'handle' parameter, providing no meaning. The description adds crucial clarification: 'by the other party's handle', specifying that the parameter is the handle of the other party. This significantly aids the agent in selecting the correct 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 action ('Remove an existing connection') and specifies the method ('by the other party's handle'). It distinguishes from siblings like 'block' or 'unfollow' which are different 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?

No guidance is provided on when to use this tool versus alternatives such as 'block', 'unfollow', or 'send_connection_request'. The agent must infer context from sibling names alone.

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 beyond annotations by stating that reports are 'publicly visible (transparency narrative)' and that the report goes 'for human review'. Annotations only indicate readOnlyHint=false and destructiveHint=false, but the description clarifies the nature of the 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?

Two sentences clearly convey the main action and an important behavioral detail. No redundant information; 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?

For a relatively simple tool with an output schema, the description covers the core purpose and a key behavioral trait (public visibility). It does not mention prerequisites or idempotency, but those are less critical given the context.

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 0%, so the description must compensate. It explains the 'reason' parameter with examples ('harassment', 'spam', 'off-topic for community'), but does not add meaning for 'target_id' or 'target_type' beyond the enum values in 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's purpose: 'Report a post, comment, profile, or DM for human review.' It specifies the verb 'report' and the resources (post, comment, profile, DM), distinguishing it from sibling tools like block or like.

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 does not provide guidance on when to use this tool versus alternatives. For example, it doesn't mention when to block instead of report, or that reporting is for content moderation while other actions are for user interactions.

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, covering safety. The description adds context about searchable fields but does not disclose pagination, sorting, or behavior for empty results. This is adequate but not rich.

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

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

The description is a single, clear sentence with no unnecessary words. It efficiently conveys the tool's function.

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 simplicity of the tool (one parameter, output schema exists), the description covers the core functionality. Additional details like case sensitivity or fuzzy matching are not necessary for basic 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 description explains that the query parameter can be a name, slug, or description keyword, adding meaning beyond the schema's type-only definition. This compensates for the 0% schema description 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 finds communities using name, slug, or description keywords. It distinguishes from sibling tools like search_posts and search_profiles by specifying the resource and search criteria.

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 like search_posts or search_profiles. There is no mention of when not to use it or any prerequisites.

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 description does not need to restate that. It adds the detail of case-insensitive substring matching, which is useful. However, no other behavioral traits (e.g., performance, scope of search) are disclosed beyond what the annotations provide. 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?

A single sentence that is front-loaded with the purpose. Every word earns its place; no verbosity or 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 existence of an output schema, the description is not required to explain return values. However, it does not mention what fields are searched (e.g., title, content) or any pagination behavior. The description is adequate but not rich, and the parameter include_avatar_blobs is left entirely to the 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 only 33% (only include_avatar_blobs has a description). The tool description adds no meaning to 'query' or 'limit' beyond implying query is the search term. It does not compensate for the low coverage, leaving the agent to infer parameter usage.

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 ('search'), the resource ('posts'), and the nature of the search ('full-text', 'case-insensitive substring'). It distinguishes the tool from sibling tools like search_communities and search_profiles by explicitly targeting posts.

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 that this tool is for searching posts, with no ambiguity. It does not explicitly state when not to use it or mention alternatives, but given the sibling list includes distinct search tools for communities and profiles, the purpose is sufficiently differentiated.

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