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

Discloses beyond annotations: bookmarks are private, server-side, no public record, keyed by post URI, rate limiting. Annotation hints (idempotentHint, destructiveHint, openWorldHint) are fully explained in the description.

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

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

Concise, front-loaded sentence, efficiently packs all key details (privacy, no-op, alternatives, auth, rate limit) 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?

Coverage of purpose, parameters, behavior, alternatives, constraints, authentication, and rate limiting is comprehensive for a simple bookmarking tool, especially with output schema present.

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

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

Schema coverage is 100%, but description adds meaningful context: specifies URI format 'at://did/app.bsky.feed.post/rkey' and explains CID is optional and auto-resolved. Adds 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 the specific action: 'Privately bookmark a post'. Distinguishes from siblings (remove_bookmark, get_bookmarks) and specifies scope ('Only posts can be bookmarked').

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: to bookmark a post. Provides alternatives: 'Use remove_bookmark to remove and get_bookmarks to list.' Mentions no-op for already-bookmarked posts and authentication requirement.

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?

Describes internal creation of a listitem record, DID resolution, and rate limiting. Annotations (destructiveHint=false, idempotentHint=false, openWorldHint=true) are consistent and the description adds context beyond 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?

Three sentences, front-loaded with key action, 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?

Covers purpose, usage, auth, alternatives, internal behavior, and output schema context. Complete for a simple two-parameter 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?

Input schema has 100% coverage with descriptions; the description adds detail about DID resolution for the actor parameter and AT-URI format for listUri.

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 'Add a user to an existing list' with a specific verb and resource. It distinguishes from siblings like remove_from_list, get_list, and create_list.

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 authentication requirement, provides alternatives (remove_from_list, get_list), and notes rate limiting.

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 openWorldHint=true. The description adds useful context: requires authentication, is read-only, and subject to per-tool rate limiting. 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 three sentences, each adding distinct value: core function, authentication/read-only, and usage alternatives. 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 10 parameters and an output schema, the description covers key aspects (purpose, auth, mutation, rate limiting, sibling differentiation) without being exhaustive. It's sufficient for most agents.

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

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

Schema coverage is 100%, so the description does not need to explain parameters. The description adds minimal extra value beyond the schema (e.g., default behavior for 'actor'). Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'analyze', the resource 'a single account', and the constraint 'along one dimension'. It also distinguishes from the sibling tool 'find_influential_users' by noting the alternative use case.

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

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

The description explicitly says 'One account-analysis tool: pick a dimension' and directs users to 'find_influential_users' for topic/search-based discovery. It also mentions authentication requirement, providing clear when-to-use and 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?

Discloses limitations (does not decode image, no pixel dimensions) and rate limiting, adding value beyond readOnlyHint and openWorldHint annotations. 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?

Five sentences covering all essentials: what it does, prerequisites, limitations, usage preference, and rate limiting. 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 output_schema exists (so return values need no explanation), annotations provide safety context, and schema covers all parameters, the description is complete: it tells what to do, prerequisites, limitations, and alternatives.

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

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

Schema coverage is 100%, baseline 3. The description adds context by explaining the blob parameter as a result from upload_image and the includeOptimizationSuggestions parameter's default behavior, but parameter details are already well-covered by 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 analyzes image blob metadata (MIME type, size, derived format, optimization thresholds) and optionally returns suggestions. It explicitly distinguishes from siblings by noting it does not decode the image and cannot report pixel dimensions, and differentiates from upload_image for pre-flight checks.

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

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

Provides explicit guidance: use upload_image first, then pass the blob reference; prefer this tool over upload_image for pre-flight size checks; notes no authentication required and rate limiting.

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 openWorldHint=true; description adds that it works without auth but richer with auth, and mentions rate limiting. 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?

Four sentences, each adding value: purpose, returns, subject types, auth, rate limiting, usage guidance. 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 output schema, return values are covered. Description covers subject types, auth dependency, rate limiting, and relationship to sibling tools. Complete.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning: explains subject format (DID or AT-URI) and includeLabels effect (faster if false). 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?

Description clearly states 'Analyze moderation status of a post or user' and lists return types. It distinguishes from sibling tools like block_user and mute_user.

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

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

Explicitly says 'Use this tool to evaluate safety before rendering content; use block_user or mute_user to act on the results.' Provides clear usage context and 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?

Discloses real writes to network, authentication need, and rate limiting. Aligns with annotations (idempotentHint=true, destructiveHint=false, openWorldHint=true). Adds 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?

Three sentences, each essential: purpose, supported actions and target formats, auth/write/rate limiting. Front-loaded with main capability. 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?

Covers main aspects: scope, actions, error handling, requirements. Output schema exists (not shown), so return values need not be explained. Minor gap: no mention of response summary structure.

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

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

Schema covers all parameters (100%). Description adds value by clarifying target formats per action and continueOnError default behavior. Baseline 3, increased for added clarity.

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 verb 'batch', resource 'same action across targets', and scope 'up to 25 targets'. Distinguishes from sibling single-action tools (follow_user, like_post, repost) by grouping multiple identical actions.

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

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

Explains when to use (batching multiple same actions) and requirements (authentication, rate limiting). Implicitly excludes single-action tools. Could be explicit about not using for mixed action types.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=false. The description adds key behavioral details: creates a block record, cannot be undone without unblock_user, requires authentication, and is subject to rate limiting. 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?

Four sentences, front-loaded with the primary purpose. Every sentence adds unique value: purpose, effect, irreversibility, authentication, sibling guidance, rate limiting. No wasted words.

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

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

Given the tool's simplicity (one parameter, simple schema), the description covers all essential aspects: purpose, effect, usage guidelines, behavioral properties, and prerequisites. Output schema exists so return values need not be described.

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

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

With 100% schema description coverage, the input schema already documents the 'actor' parameter well (handle or DID). The description adds no further parameter details, so baseline 3 is appropriate.

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

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

The description uses a specific verb 'Block' with resource 'user' and clearly states the effect: preventing the user from seeing content and interacting. It distinguishes from sibling tool 'mute_user' by explicitly contrasting the behavior.

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

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

The description explicitly states when to use this tool ('for mutual visibility restriction'), provides an alternative ('use mute_user instead...'), notes the irreversibility without calling unblock_user, and requires authentication. All guidelines are explicit.

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 include destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds that authentication is required, lists are permanent, and there is per-tool rate limiting. This supplements the annotations well.

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

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

Two sentences that efficiently convey the core action, prerequisites, lifecycle, and related tools. 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 three parameters and presence of an output schema, the description covers creation, authentication, persistence, and rate limiting comprehensively. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds context by explaining the purpose parameter's enum values and the characters of name and description. It provides meaning beyond the schema.

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

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

The description clearly states the tool creates a list for organizing users (curatelist) or moderation (modlist). It distinguishes from siblings like add_to_list, remove_from_list, and get_list by explaining their roles.

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 when to use (create lists), mentions authentication and rate limiting, and hints at alternatives for managing and inspecting lists. However, it does not explicitly exclude cases where other tools should be preferred.

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 important behavioral traits beyond annotations: the post is public, subject to rate limiting, requires auth, and creates additional records (threadgate, postgate) for reply/quote controls. It also explains side effects and error handling for gate write failures.

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

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

The description is well-structured with a clear opening, a list of supported features, side effects, and alternatives. It is somewhat lengthy due to the tool's complexity, but every sentence contributes meaningful information. Slightly more conciseness could be achieved by reducing redundancy.

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

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

Given the tool's complexity (8 parameters, nested objects, output schema present), the description covers all necessary aspects: main functionality, usage modes, side effects, preconditions, and error handling. It leaves no significant gaps for an agent to misinterpret.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining mutual exclusivity among embed types, auto-detection of facets, and the relationship between reply controls and threadgate records. This provides context that enriches the 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's purpose: 'Create a new post on AT Protocol (Bluesky).' It explicitly distinguishes itself from sibling tools like create_thread and reply_to_post by stating when to use each.

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 guidance on when to use this tool versus alternatives: 'Use create_thread to publish a multi-post chain... and reply_to_post to reply...; use this tool for a single standalone post.' It also mentions prerequisites (authentication, app password) and side effects.

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

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

Adds significant behavioral context beyond annotations: auto-chaining, partial failure handling with failedAtPosition, threadgate writing after publication, and rate limiting. 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?

Concise paragraph with front-loaded purpose. Every sentence adds value – 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?

Comprehensive for a tool with 3 params and nested objects. Covers partial failure, authentication, rate limiting, and sibling differentiation. Output schema exists, so return values are covered.

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

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

Schema has 100% description coverage, so baseline is 3. The description adds extra semantics like chaining behavior, replyControls timing, and failure handling, earning a 4.

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

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

The description clearly states it creates a thread of 2-25 posts, auto-chaining them, and distinguishes from create_post and reply_to_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?

Explicitly states when to use this tool versus alternatives (create_post for single posts, reply_to_post for appending to existing threads). Also mentions authentication and optional replyControls.

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?

Reinforces destructiveHint by noting 'Permanently removes... cannot be undone'. Adds context about authentication and rate limiting not covered by annotations. No contradiction.

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

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

Two short, front-loaded sentences with no waste. First sentence states purpose, second provides usage and behavioral context.

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?

Complete given the simple input (1 required param with full schema coverage) and presence of output schema. Covers purpose, usage, behavior, and constraints.

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

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

Schema coverage is 100%, baseline 3. Description adds the constraint that the URI must belong to the authenticated user, providing extra clarity beyond the schema's 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?

Clearly states 'Delete a post on AT Protocol', specifying the verb and resource. Distinguishes from siblings like create_post and reply_to_post by noting its use for removal.

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 'Use this instead of create_post/reply_to_post when you need to remove existing content', providing clear when-to-use guidance. Also mentions authentication and rate limiting.

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 value beyond the annotations: it states authentication requirement (app password), mentions per-tool rate limiting, and describes the two discovery modes. This is consistent with the readOnlyHint and openWorldHint annotations and provides additional 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 and front-loaded: it starts with the core purpose, then adds key details (auth, read-only, modes, alternatives, rate limiting). Every sentence is necessary and well-structured.

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

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

Given the tool's complexity (11 parameters, 1 required, output schema exists), the description is complete. It covers purpose, authentication, read-only, mode differentiation, sibling alternatives, and rate limiting. The input schema provides detailed parameter info, and the output schema is present, so no further return value explanation is needed.

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 documentation coverage is 100%, so baseline is 3. The description adds value by explaining the two modes and how parameters relate to each mode (e.g., 'limit' behavior differs by mode). This extra context helps the agent understand parameter usage beyond individual 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's purpose: 'Surface content from your own home timeline.' It specifies it is read-only, requires authentication, and offers two modes. It distinguishes from siblings by explicitly naming 'find_similar_users' and 'discover_communities' as alternatives.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: it tells the agent to use find_similar_users for similar accounts and discover_communities for topic-based communities. It also notes authentication requirements and read-only nature.

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 the reading behavior (clustering posts/authors) which aligns with annotations (readOnlyHint). Adds context about authentication and rate limits, going beyond the annotations to inform the agent of constraints and richer functionality.

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 concise sentences with no redundant information. Each sentence serves a distinct purpose: stating the primary function, authentication, differentiation from a sibling, and rate limiting. It is front-loaded with the core action.

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 (no need to describe returns), the description covers the tool's behavior, authentication, rate limiting, and relationship to a sibling tool. It is complete for a tool of this complexity with good annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add new parameter details beyond what the schema provides, but it provides overall context for how parameters ('topic') are used (searching posts and clustering authors), which is adequate.

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 discovers topic-based communities by searching posts and clustering interacting authors. It distinguishes itself from the sibling 'find_similar_users' by specifying when to use each, making the purpose unambiguous.

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

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

Explicitly mentions authentication requirements ('Works without authentication; richer with auth'), provides a condition for use ('Use this instead of find_similar_users when you want topic-based community clusters'), and notes rate limiting ('Subject to per-tool rate limiting').

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; description reinforces with 'Read-only — produces no side effects' and adds rate limiting note. No contradictions, and adds context about auth modes.

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

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

Three sentences, each adding value: purpose, auth/read-only note, usage comparison, rate limit. Front-loaded and no fluff.

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

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

Given output schema exists, description covers usage, safety, and rate limiting. Does not detail output structure or data freshness, but sufficient for a read-only 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 does not add extra meaning beyond schema; it lists no parameter details but provides general 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?

Clearly uses verb 'Find' with specific resource 'influential users' and method 'searching recent posts and ranking their authors'. Distinguishes from sibling tool find_similar_users by highlighting topic-driven discovery vs social graph.

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 find_similar_users and notes authentication requirements (works without, richer with). Does not explicitly state when not to use, but provides clear context.

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

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

Beyond annotations (readOnlyHint, openWorldHint), the description discloses that content-topic similarity is NOT analyzed, adding important behavioral context. No contradictions with annotations.

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

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

Three concise sentences, each serving a distinct purpose: algorithm definition, exclusion note, and usage guidance. 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 an output schema exists, the description covers purpose, algorithm, limitations, authentication, and alternatives comprehensively. No missing context for effective use.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds algorithmic context (second-degree follows, follower ratio) that enhances interpretation of parameters, though it does not describe each parameter individually 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 tool finds users similar to a given user based on share follow-graph connections, specifying the mechanism (second-degree follows, follower/following ratio) and explicitly distinguishing from search_actors.

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 when-to-use guidance: 'Use this instead of search_actors when you want accounts structurally similar to a known user rather than keyword matches.' Also notes authentication effects and rate limiting.

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 value beyond annotations: duplicates return existing URI without creating new record, requires authentication app password, subject to rate limiting. Consistent with 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?

Three focused sentences: action description, duplicate handling, usage guidance. No fluff.

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

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

Completely covers the behavior, idempotency, auth, rate limits, and alternative tools for a simple follow action with one parameter.

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 100% and parameter description already explains 'actor' as Handle or DID. Description adds no new parameter information beyond schema.

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

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

Clear verb ('Follow') and resource ('a user on AT Protocol') with precise description of creating a follow record. Distinguishes from sibling tools 'unfollow_user' and 'batch_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?

Explicitly states when to use (follow a user), when not (if already followed, no duplicate), and alternatives (unfollow_user, batch_action). Includes authentication and rate limit context.

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

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

Annotations provide readOnlyHint and openWorldHint. Description adds concrete behavioral details: fetches up to 2 MB HTML and 1 MB image, SSRF-safe, optionally uploads blob. 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 well-structured sentences, no redundancy. Front-loaded with core purpose, each sentence adds unique 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 one parameter, output schema exists, and annotations present, the description fully covers prerequisites, alternatives, security, and process. Highly complete.

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

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

Schema covers URL format and constraints (100% coverage). Description adds meaning by explaining the extraction process (OG/meta tags, blob upload) and return type. Baseline 3, plus extra 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 clearly states it generates a link preview with title, description, and thumbnail, specifying the verb 'Generate' and resource 'link preview'. It details the process (fetching, extracting meta tags, uploading thumbnail) and distinguishes from sibling tools like upload_image and upload_video.

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

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

Explicitly says 'Use this tool before create_post when you want a rich URL card; use upload_image or upload_video for local media instead.' Also mentions authentication requirement and rate limiting.

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 and openWorldHint. The description adds value by stating the tool works without authentication and is subject to rate limiting, which are behavioral traits beyond what annotations provide.

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

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

The description is four sentences, each serving a distinct purpose: purpose, auth behavior, scope, and differentiation with rate limit. 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 4 parameters (100% schema coverage) and presence of an output schema, the description covers necessary context: auth behavior, differentiation, and rate limiting. It is largely complete, though could mention pagination briefly, but cursor is in 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%, so baseline is 3. The description does not add additional meaning to any parameter beyond what is already in the schema. It mentions 'Lists a specific user's posts' but that is about tool scope, not specific 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 'Retrieve posts by a specific AT Protocol user,' using a specific verb and resource. It also distinguishes from siblings 'get_timeline' and 'search_posts' by explaining their different purposes.

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

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

The description provides context on authentication behavior ('Works without authentication; richer with auth') and explicitly contrasts with two sibling tools. It does not give explicit when-not-to-use guidance but sufficiently implies usage context.

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

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

The description adds value beyond annotations: explains read-only operation, authentication requirements, rate limiting, cursor pagination, and unavailable reasons. No contradiction with annotations (readOnlyHint, openWorldHint).

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

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

Three sentences, no wasted words. First sentence states purpose, second details return behavior, third covers authentication and sibling tools. Well-structured 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?

With output schema present, return values need no explanation. Description covers pagination, authentication, rate limiting, and error states (unavailable reasons). Fully complete for a read-only listing tool.

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

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

Schema coverage is 100% with parameter descriptions already in the schema. The description mentions cursor pagination but adds no new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'List the authenticated account's private bookmarks' with a specific verb and resource. It also distinguishes from sibling tools add_bookmark and remove_bookmark.

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 for when to use (list bookmarks) and mentions management via siblings. While it doesn't explicitly state when not to use, the pagination, authentication, and rate-limit discussion offer sufficient 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 (destructiveHint=false, idempotentHint=true) are consistent. Description adds: read-only default, markRead effect (clears unread count), auth requirement, rate limiting. No contradiction.

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

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

Single paragraph, every sentence provides essential information. Front-loaded with main action, no superfluous text.

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 aspects: purpose, pagination, side effect, auth, sibling tools, rate limiting. Output schema exists, so return values need not be detailed. 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?

Schema coverage is 100%, baseline 3. Description adds meaningful context: convoId source, markRead side effect, cursor default behavior, limit ordering. Adds 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?

Clear verb (read) and resource (messages of a Bluesky direct-message conversation). Differentiates from siblings list_conversations (to find IDs) and send_direct_message (to reply).

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 mark read (only when markRead=true), prerequisites (app password with DM access), and when to use siblings (list_conversations, send_direct_message). Also mentions rate limiting.

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, openWorldHint=true), the description adds meaningful behavioral traits: authentication variability, pagination cursor mechanism, return structure (feed generator metadata + posts), and rate limits. 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?

Four concise sentences, front-loaded with the core purpose, no redundant or irrelevant information. Every sentence contributes distinct value (purpose, auth, pagination, sibling distinction, rate limit).

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 essential aspects for selecting and invoking this tool: purpose, authentication, pagination, sibling differentiation, and rate limiting. With an output schema present, the description does not need to detail return values further.

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

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

Schema coverage is 100%, so the schema already documents 'feedUri', 'limit', and 'cursor' thoroughly. The description adds the cursor pagination hint but otherwise doesn't exceed the schema's parameter descriptions, justifying the baseline score of 3.

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

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

The description clearly states the tool retrieves posts from a custom algorithm feed, specifying the resource ('custom algorithm feed') and action ('get posts'). It explicitly distinguishes from the sibling 'get_timeline' by naming the alternative use case.

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

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

Provides explicit guidance on when to use this tool ('use get_timeline for the authenticated user's home feed instead') and notes authentication levels ('works without authentication; richer with auth'). Also mentions rate limiting, helping the agent decide contextually.

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 read-only and open world. Description adds pagination behavior with cursor, auth expectations, and mentions per-tool rate limiting. Slightly vague on rate limiting details but sufficient.

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

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

Three sentences, each delivering unique information: purpose, auth/pagination, and modification alternative. No fluff. Front-loaded with key 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?

Covers all key aspects: purpose, auth, pagination, modification alternatives, rate limiting. Output schema exists so return values not needed. Highly complete for a retrieval 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 has 100% coverage, so the description adds value by explaining the pagination flow ('use the returned cursor to fetch subsequent pages') and the default/range for limit is in schema. No contradictions.

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 'Get the contents of a list, including all users in the list.' Uses specific verb 'get' and identifies the resource 'list' with scope 'contents and users'. Distinguishes from sibling tools that modify membership.

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

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

Explicitly tells when to use ('Get the contents...') and when not ('Use add_to_list / remove_from_list to modify'). Also notes authentication behavior ('Works without authentication; richer with auth').

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, openWorldHint), the description adds value: requires auth, subject to rate limiting, countOnly skips full list. 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?

Three sentences, each purposeful, front-loaded with main action. 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 read-only list tool with 4 parameters (all documented), annotations, and output schema, the description covers auth, rate limits, special logic (countOnly), and sibling reference. No gaps.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description reinforces countOnly but adds no new parameter semantics. Baseline 3 is appropriate.

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

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

The description starts with a clear verb ('Retrieve') and specific resource ('notifications from AT Protocol'), listing types (likes, reposts, etc.). It distinguishes itself from siblings like mark_notifications_seen by explicitly mentioning it.

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

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

Provides explicit guidance: when to use countOnly for cheap badge count, when to use mark_notifications_seen to clear state. Also notes authentication and rate limiting, helping the agent decide context.

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

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

Annotations already declare readOnlyHint and openWorldHint. Description adds behavioral details: works without authentication but richer with auth, subject to per-tool rate limiting, and that it replaces older tools. This provides useful context beyond the annotations, though no contradictions.

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

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

Description is front-loaded with the core purpose. Five short sentences each add unique value: purpose, usage pattern, replacement info, auth behavior, and rate limiting. No wasted words.

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

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

Given the tool's complexity (7 parameters, 1 required), presence of output schema, and annotations, the description covers key aspects: what it does, how to use flags, auth implications, rate limits, and relationship to previous tools. It is fully sufficient for an agent to 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 100%, so the schema fully documents parameters. The description adds value by summarizing the include* flags and noting the default behaviors (e.g., 'Default true' for include flags). It does not repeat all schema details, but the additive context is helpful.

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 'Get comprehensive post information in a single call' and 'Single post reader', with specific mention of include* flags for thread, author, engagement, and media. It explicitly replaces former tools get_thread and extract_media_from_post, distinguishing itself effectively from 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?

Description provides clear context for when to use: 'Get comprehensive post information in a single call' and mentions it replaces previous tools. It also notes authentication options and rate limiting. However, it does not explicitly list when not to use this tool versus other sibling tools like get_author_feed or search_posts, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint and openWorldHint. Description adds that no authentication is required, is subject to rate limiting, and specifies exact return fields. 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?

Single paragraph, three sentences. First sentence defines core action and return values, second provides usage context, third adds constraints. No redundant information.

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

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

Given the simple single-parameter tool with an output schema, the description covers purpose, parameters, usage boundaries, and practical limitations (rate limiting, short link issue). Complete for selection and invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats the same parameter info from the schema (AT-URI or bsky.app link, unsupported short links) without adding new meaning beyond what the schema provides.

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

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

Clearly states the tool fetches a Bluesky starter pack by AT-URI or bsky.app link, and lists the returned data (name, description, creator, etc.). Differentiates from siblings like search_starter_packs and get_list.

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

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

Explicitly tells when to use this tool (to fetch a specific pack) and when to use alternatives (search_starter_packs for discovery, get_list for full member list). Also notes it works without authentication and is rate-limited.

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 and openWorldHint; description adds authentication requirement (app password) and rate limiting, providing extra 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?

Three concise sentences, front-loaded with key 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?

Covers all necessary context: resource, authentication, pagination, rate limiting, and differentiation from sibling; output schema exists to handle return values.

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

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

Schema coverage is 100% with clear descriptions for all three parameters; description does not add significant meaning beyond the schema, so baseline score of 3 applies.

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

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

Description uses specific verb 'Retrieve', clearly states resource 'user's home timeline', and distinguishes from sibling tool 'get_author_feed' for specific user feeds.

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 (home timeline), when not to use (use get_author_feed for specific user), and notes authentication and rate limiting requirements.

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

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

Beyond annotations (readOnly, openWorld), description adds that auth is optional but enriches results, notes rate limiting, and implies pagination via cursor, offering full behavioral context.

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

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

Two well-structured sentences with front-loaded purpose, minimal waste, and clear separation of guidance.

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 authentication, pagination, rate limiting, and use cases; no gaps for a moderately 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%, so baseline 3 applies. Description reinforces direction parameter and mentions rate limiting but adds no new parameter-level detail 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 specifies the tool retrieves followers or follows from AT Protocol, and distinguishes from siblings like get_user_profile and get_user_summary by noting they are for aggregate counts.

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 authentication behavior, gives direction parameter usage, and directs users to alternative tools for aggregate counts, providing clear when-to and when-not-to 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 and openWorldHint. Description adds behavioral details beyond annotations: lists exact fields returned, explains that authenticated calls include viewer-specific fields (following, followedBy, muted, blocking, blockedBy), and mentions rate limiting. No contradiction; adds value.

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

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

Three sentences, each earning its place: first sentence states core function and output, second adds authentication nuance, third provides alternatives and rate limit info. Front-loaded with essential info, no redundancy.

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

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

For a simple read tool with one required param and an output schema, the description covers all key aspects: purpose, return fields, auth behavior, alternatives, and rate limiting. No gaps. Sibling tools are numerous but differentiated well.

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 a clear description of the 'actor' parameter (handle or DID). Description does not add additional semantic meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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 retrieves a user profile from AT Protocol and lists key fields (handle, display name, bio, etc.). It distinguishes itself from siblings by noting auth-dependent richness and explicitly names alternatives (get_user_summary, get_user_connections). The verb 'retrieve' plus resource 'user profile' is specific.

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

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

Provides explicit guidance: works without auth but is richer with auth; recommends get_user_summary for condensed overview and get_user_connections for follower/following lists. Also mentions rate limiting. Tells when and when not to use this tool effectively.

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 (non-destructive) and openWorldHint=true (variable results). Description adds behavior beyond annotations: mentions rate limiting and authentication sensitivity, which are useful for agent decision-making.

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

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

Two concise sentences that front-load the purpose, then provide usage guidelines and behavioral notes. Every sentence adds value with no wasted words.

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

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

Given 4 parameters with 100% schema coverage, presence of output schema, and comprehensive annotations, the description is fully adequate. It covers purpose, alternatives, authentication behavior, and rate limiting, leaving no gaps for agent comprehension.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond what the schema provides; it mentions authentication context but does not elaborate on parameter usage or dependencies 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 uses a specific verb ('Get'), identifies the resource ('comprehensive user information'), and distinguishes from sibling tools like get_user_profile and get_author_feed by stating it combines profile, recent posts, and engagement statistics in one call.

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 ('when you need both in one round-trip'), when not to use (alternatives get_user_profile and get_author_feed), and authentication context ('Works without authentication; richer with auth').

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 idempotency, authentication, and rate limiting beyond annotations. No contradiction with annotations (destructiveHint=false, idempotentHint=true). Adds valuable behavioral context.

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

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

Concise, front-loaded with main action, and every sentence adds value. No wasted words.

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

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

Covers authentication, idempotency, rate limiting, and references output schema (even if not shown). Complete for a simple mutation tool with good annotations and 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%, so baseline is 3. The description does not add extra meaning beyond the schema; it only indirectly references parameters. No new semantic information provided.

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: 'Like a post on AT Protocol by creating a like record that references the target post.' It uses a specific verb (like) and resource (post), and distinguishes from sibling tools like unlike_post.

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

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

Provides explicit when-to-use (liking a post), idempotency behavior (if already liked, returns existing like), alternative (unlike_post), authentication requirement, and rate limiting. Clearly guides the 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 openWorldHint=true. The description adds authentication details (app password with DM access), rate limiting, and a comprehensive list of return fields (id, members, unread count, mute state, status, last-message preview, cursor). No contradictions.

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

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

The description is concise, comprising two sentences with front-loaded purpose. The parenthetical endpoint detail is slightly verbose but not excessive.

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

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

Given the tool's complexity (3 optional parameters, output schema present, annotations), the description comprehensively covers purpose, usage context, return format, authentication, rate limiting, and sibling tool references.

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

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

Schema coverage is 100% and the description does not add additional meaning beyond the schema for the three parameters (limit, cursor, status). The return field mentions cursor and status, but that is output, not parameter semantics. Baseline 3 applies.

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

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

The description clearly states the tool lists the authenticated user's Bluesky direct-message conversations. It specifies the endpoint and service, and distinguishes it from sibling tools like get_conversation_messages and send_direct_message.

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

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

Explicit guidance on when to use alternatives: 'Use get_conversation_messages to read a conversation and send_direct_message to reply.' Also mentions authentication requirements.

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

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

Description adds that the action persists the seen cursor server-side and is subject to rate limiting, which supplements annotations (destructiveHint: false, idempotentHint: false, openWorldHint: true). 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 sentences, each carrying distinct information: purpose, authentication, persistence and usage. No fluff; front-loaded with the core action.

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 optional parameter and an output schema (existence known), the description covers purpose, prerequisites, side effects, rate limiting, and relationship to sibling tool. 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 single parameter seenAt is described in schema as ISO 8601 timestamp defaulting to now. Description reinforces this and clarifies effect. With 100% schema coverage, description adds value by explaining the default behavior.

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 marks notifications as seen up to a timestamp, distinguishing it from the sibling tool get_notifications (which retrieves notifications). The verb 'mark' and resource 'notifications' are specific.

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

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

Description mentions authentication requirement and per-tool rate limiting, and advises using get_notifications to retrieve new notifications. Provides clear context but does not explicitly 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 key behaviors: muted user is not notified, requires authentication, subject to rate limiting, and idempotent (consistent with idempotentHint). No contradiction with annotations (destructiveHint=false, idempotentHint=true, openWorldHint=true).

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

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

Two sentences that are front-loaded and efficient, covering behavior, comparison to sibling, and required context (auth, rate limits). 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?

For a simple tool with one parameter, an output schema, and annotations, the description fully covers purpose, usage guidelines, and behavioral transparency. No gaps.

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

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

Schema coverage is 100% with a clear description for the 'actor' parameter. The description adds no additional meaning beyond the schema, meeting the baseline of 3.

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

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

The description clearly states the verb 'mute' and the resource 'user', explaining that it hides content from feeds and notifications without notification. It also distinguishes from block_user, making its purpose unique 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?

Explicitly describes when to use mute_user vs block_user with clear criteria: 'mute_user for a soft, private suppression; block_user when you need to prevent target interaction'. Also mentions authentication requirement and rate limiting.

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?

Describes idempotent behavior ('removing a bookmark that does not exist succeeds as a no-op'), authentication requirements ('requires authentication (app password)'), and rate limiting. Adds value beyond annotations like destructiveHint and idempotentHint.

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

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

Four sentences, front-loaded with purpose, no redundant information. Efficiently covers usage, behavior, and auth.

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 (inferred), description fully explains behavior (no-op), auth needs, and rate limiting. Complete for a simple removal tool with one parameter.

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?

Provides context on the 'uri' parameter beyond schema: clarifies that bookmarks are keyed by post URI, not a bookmark-record URI, and instructs to pass the post URI directly. With 100% schema coverage, this is useful additional 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?

Clearly states the action (remove a private bookmark) and resource (post bookmark on AT Protocol). Distinguishes from siblings by mentioning add_bookmark and get_bookmarks, providing contrast.

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

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

Explicitly says when to use this tool (to remove a bookmark), what happens if bookmark doesn't exist (no-op), and references alternatives (add_bookmark, get_bookmarks).

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

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

Beyond annotations (destructiveHint, idempotentHint, openWorldHint), the description explains the internal process: resolving the handle to a DID, paging through the list, and deleting the record. It also mentions authentication and rate limiting, adding valuable behavioral context.

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

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

The description is three sentences, front-loaded with the purpose, then the process, then guidance. No unnecessary words; 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 existence of an output schema, the description covers the key aspects: purpose, authentication, process, alternatives, and rate limiting. It might lack error scenarios, but overall it is sufficiently complete for a moderately 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 description coverage is 100%, so parameters are well-documented. The description does not add extra meaning to the parameters beyond what is in the schema; it focuses on the process. Thus, the baseline of 3 is appropriate.

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

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

The description begins with 'Remove a user from an existing list,' which clearly states the verb and resource. It further distinguishes from siblings by mentioning add_to_list and get_list as alternatives, providing differentiation.

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

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

The description explicitly advises using add_to_list to re-add a member and get_list to inspect current members, offering clear context for when to use alternatives. It implies authentication and rate limiting but does not explicitly state when not to use the 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?

Description adds value beyond annotations by noting it creates a new post record, cannot be undone (delete_post as fallback), requires authentication, and is subject to rate limiting. No contradiction with annotations (destructiveHint false, idempotentHint false, openWorldHint 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?

Four sentences that are front-loaded with the core action and then provide alternatives, behavioral notes, and constraints. No wasted words; 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's complexity (4 params, output schema), the description covers purpose, usage guidelines, behavioral traits, and parameter context adequately. Mentions rate limiting and undoability, leaving no critical gaps.

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

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

While input schema covers all parameters with descriptions, the tool description adds semantic context for root and parent parameters (e.g., root must be original top-level post). Schema coverage is 100%, so baseline is 3; additional guidance justifies 4.

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

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

The description clearly states the tool's purpose: replying to an existing post on AT Protocol with proper thread references. It uses specific verbs ('reply', 'creating') and distinguishes itself from siblings like create_post and create_thread.

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 ('when the new content belongs inside an existing thread') and when to use alternatives ('use create_thread to start a multi-post thread from scratch'). Also mentions authentication requirements and that the action cannot be undone.

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

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

The description adds significant behavioral context beyond annotations: the report is asynchronous, cannot be withdrawn, requires authentication (app password), and is subject to per-tool rate limiting. This aligns with the 'destructiveHint: true' annotation.

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

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

The description is three sentences with no fluff. It front-loads the purpose, then provides key behavioral details, and finishes with sibling differentiation. 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 complexity, presence of an output schema, and thorough annotations, the description covers purpose, usage guidelines, behavioral traits, and parameter hints adequately. It is complete for an agent to select and invoke correctly.

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

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

The input schema covers all parameters with descriptions (100% coverage). The description only adds minimal extra value, noting that providing a reason helps moderators act faster. The baseline of 3 is appropriate.

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

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

The description clearly states the tool reports content that violates community guidelines or terms of service, using the verb 'report' and specifying the resource as content. It distinguishes itself from the sibling 'report_user' by stating when to use each.

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 provides guidance on when to use this tool (when you have AT-URI and CID) versus the alternative 'report_user' (for accounts). It also mentions required authentication, async review, and non-withdrawal.

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

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

Discloses that reports are irreversible ('cannot be withdrawn once submitted'), requires authentication ('app password'), and is subject to rate limiting. Annotations indicate destructive hint, which aligns with the description. 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 sentences, each serving a distinct purpose: stating the action, providing usage context, and differentiating from sibling. 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 full schema coverage, annotations, and output schema, the description covers all necessary aspects: purpose, behavioral details, usage guidance, and differentiation. No gaps.

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

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

Schema description coverage is 100%, so the schema already fully explains each parameter. The description does not add new information beyond what is in the schema, meeting the baseline for high coverage.

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

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

Clearly states the action ('report a user account'), the resource ('account'), and the scope ('entire account'). Differentiates from sibling 'report_content' by specifying that this tool targets accounts, not specific 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?

Explicitly provides when to use this tool ('report a user account') and when to use the alternative ('use report_content when the violation is limited to a specific post'). Also notes that reports are reviewed asynchronously and cannot be withdrawn.

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 provide minimal hints (non-destructive, not idempotent, open world). The description adds valuable behavioral context: requires authentication, deduplicates plain reposts for safe retries, differentiates two modes, and notes rate limiting. 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?

Four concise sentences, front-loaded with main purpose. Every sentence adds information: main action, two modes with optional text, authentication and safety note, rate limiting. 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 tool complexity (two modes), presence of output schema (handled elsewhere), and annotations, the description is complete. It covers authentication, retry safety, rate limits, and guidance for removal via sibling tool.

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

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

Schema already covers all parameters with descriptions (100% coverage). The description adds value by explaining the effect of the optional 'text' parameter (triggers quote post) and providing practical guidance on deduplication for plain reposts.

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 ('Repost content on AT Protocol') and distinguishes between two distinct behaviors: plain repost and quote post with optional text. It also differentiates from sibling tool 'unrepost' for removal.

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 (repost/quote post) and when not to (use unrepost for removal). Provides guidance on safety of retrying plain reposts due to deduplication, and mentions authentication and rate limiting constraints.

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 and openWorldHint; description adds context about unauthenticated vs authenticated usage and rate limiting, enhancing 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?

Three sentences, front-loaded with purpose, no extraneous words; efficient and well-structured.

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

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

Given output schema exists, description covers purpose, usage guidelines, authentication context, and rate limiting, making it complete for a search tool.

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

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

Schema description coverage is 100%, so baseline is 3; description does not add much beyond schema, only providing a search example, which is marginal added value.

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

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

Clearly states it searches AT Protocol accounts by handle or display name, and distinguishes from get_user_profile by specifying when to use each.

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 vs get_user_profile, mentions authentication options and rate limiting, providing clear guidance on when and how 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 declare readOnlyHint=true and openWorldHint=true. The description adds further behavioral context: authentication requirement, per-tool rate limiting, and paginated results sorted by recency or engagement. 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 efficiently convey the core action, filters, pagination, authentication, sibling tool, and rate limiting. 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 presence of an output schema (not shown but indicated), the description adequately covers the tool's purpose, filter capabilities, pagination, authentication, and rate limits. It is complete for a search tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by summarizing the types of filters (author, language, date range, mentions, domain, URL) and mentioning pagination (cursor), going beyond what the schema provides individually.

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 searches for posts on Bluesky using full-text queries with optional filters. It distinguishes from sibling tools like search_actors by specifying the tool's scope (posts vs. users).

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 guidance: requires authentication (app password), subject to per-tool rate limiting, and suggests using search_actors to find users instead of posts. This helps the agent choose the right 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 readOnlyHint and openWorldHint. The description adds useful context: pagination, return fields, and rate limiting. 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 succinct sentences: purpose, return summary, and usage guidance. No filler, front-loaded with the primary action.

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, return fields, pagination, authentication, rate limiting, and alternative tool. The presence of an output schema reduces burden on description. Lacks error handling notes but is adequate.

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

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

Schema coverage is 100%. The description adds valuable detail for the 'q' parameter, noting that plain keywords work but Lucene syntax is recommended. This goes beyond the 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?

Clearly states the verb 'search', the resource 'Bluesky starter packs', and the method 'by keyword'. References the underlying API function and distinguishes from sibling tool get_starter_pack, which fetches full details for a specific pack.

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 'Works without authentication' for context and recommends get_starter_pack for detailed information. Lacks an explicit 'when not to use', but the alternative is clearly specified.

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

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

The description adds significant behavioral context beyond annotations: authentication requirements, rate limiting, text length limits (graphemes/bytes), no facets behavior, and automatic conversation creation. The annotations only provide destructiveHint, idempotentHint, and openWorldHint, so the description carries the full burden and exceeds it.

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 each sentence provides necessary detail. The main action is front-loaded. Minor redundancy in repeating 'plain text' but overall well-structured.

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

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

Given the tool's complexity (two target modes, constraints, auth), the description covers all essential aspects for correct invocation. An output schema exists, so return values are not needed. The description is complete and actionable.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaning by specifying max lengths, the no-facets behavior, the API calls involved (chat.bsky.convo.sendMessage, chat.bsky.convo.getConvoForMembers), and the mutual exclusivity of convoId and member. This adds substantial value beyond the schema.

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