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

Annotations already declare destructive=true, but the description adds substantial context they cannot convey: visibility to the target, mutual follow removal, post hiding, that the action is reversible yet the follows are not restored, and the confirm requirement. This is exactly the extra behavioral detail the structured fields cannot carry.

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?

Front-loaded purpose followed by tightly packed, high-value clauses about side effects and reversibility. No filler; 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?

With no output schema, the description still covers the side effects, reversibility, non-reversible consequence, and the confirm requirement. Nothing an agent needs to invoke this destructive tool correctly is missing.

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 all three parameters are already documented in the schema, including confirm's "set true only when the user asked for exactly this action." The description's "Needs confirm: true" reinforces but adds little beyond the schema. Baseline 3 is correct.

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

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

States a specific verb and resource ("Block an account") and immediately distinguishes it from a plain hide by noting it is bidirectional and visible to the target. An agent can separate it from mute_account by the both-directions severing behavior without opening the schema.

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 names the reversal path (unblock_account) and the precondition that the call needs confirm: true. It lacks an explicit contrast with the sibling mute_account (when to block vs when to mute), which is the one obvious alternative an agent would weigh.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotency, so the safety profile is partly covered. The description adds genuinely non-structured context: the post goes public the instant it runs (hence confirm), and URLs/hashtags/mentions are auto-linked without manual formatting. It does not discuss failure/reversibility, but the added behavioral notes are substantive.

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?

Roughly five compact sentences, all front-loaded: purpose first, capabilities next, then the character limit + sibling alternative, then the confirm gate. No filler or repetition of schema 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?

For a 13-parameter mutation with 100% schema coverage and no output schema, the description covers what an agent needs to invoke it safely: scope, media capabilities, length ceiling, sibling alternative, and the confirm requirement. Only failure modes and the resulting post identifier are left unaddressed, which is minor.

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 every parameter is already documented and the baseline is 3. The description reinforces the 300-character limit and auto-linking but adds little parameter detail beyond what the nested schema already carries (alt text, media constraints, reply_control semantics, account selection).

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

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

States a specific verb and resource ("Publish a post") and enumerates the content shapes it supports (text, images+alt, video, link card, quote, replies), so an agent can immediately match it to a publishing intent. It also names create_thread as the boundary case for longer content, distinguishing it from the nearest sibling.

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?

Gives an explicit alternative with its selecting condition (over 300 characters → create_thread) and states the precondition that the action is public immediately and therefore requires confirm: true. It doesn't cover other adjacent cases (editing, deleting, scheduling), but the core routing guidance is clear.

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

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

Annotations already flag destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety bar is partly met. The description adds real context annotations cannot convey: all parts are validated against the 300-char limit before anything posts (no half-published threads), and media/quote/reply controls attach only to the first post. It does not describe rate limits or the return shape.

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

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

Four tight sentences, front-loaded with the core action, then atomicity guarantee, then attachment scoping, then the confirm gate. No filler, and each sentence carries distinct information.

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

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

For a 9-param mutation with nested objects and no output schema, the description covers the high-risk behaviors (atomic validation, first-post-only attachments, confirm gate). It omits the return value/thread identifier and does not restate the account default, leaving a small gap an agent might notice.

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 89%, so the baseline is 3. The description earns above baseline by clarifying scope that the schema leaves ambiguous: 'Media, quotes and reply controls apply to the first post' tells the agent that quote, images and reply_control are not per-part, which no parameter description states.

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

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

States a specific verb+resource: 'Publish several posts as one thread, each replying to the last.' The multi-post/threaded nature clearly separates it from a single-post sibling like create_post, though it never names that sibling explicitly.

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

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

Usage is implied rather than stated: the confirm:true requirement and the atomicity note hint at when this is appropriate, but the description never says 'use this instead of create_post when you have multiple parts' or sets any preconditions beyond confirm.

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 destructive=true and idempotent=false, and the description adds genuinely new behavior: the action is irreversible and, notably, 'does not remove the post from feeds and caches that already have it'. That caching/eventual-consistency caveat is exactly the kind of nuance the agent needs and is not derivable from the annotations.

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

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

Two tight sentences, front-loaded with the action and scope, then the irreversible/caching caveat, then the confirm requirement. Every clause carries information; no padding.

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 3-param mutation with full schema coverage and annotations that already flag destructiveness, the description supplies the missing pieces: irreversibility, the caching limitation, and the confirmation gate. Nothing an agent needs to invoke it safely is absent.

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 uri, account, and confirm are already documented, including the confirm semantics ('set true only when the user asked for exactly this action'). The description restates the confirm requirement but adds no new syntax or format detail, so the 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?

States a specific verb and resource ('Delete ... post') and narrows scope with 'one of your own posts', which cleanly separates it from create_post, like_post, and the other post siblings. An agent can identify the operation and its target without opening the schema.

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 surfaces a real prerequisite ('Needs confirm: true') and scopes the action to the user's own posts, but gives no explicit when-to-use / when-not-to-use framing. With no sibling delete/undo tool, routing ambiguity is low, so this is adequate but not exemplary.

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=false, idempotentHint=true, and destructiveHint=false, so the description's 'Following twice is harmless' merely restates the idempotentHint. Beyond that, nothing new is disclosed about auth requirements, visibility of the follow (public/private accounts), or rate limits.

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

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

Two short sentences, front-loaded with the action and identifier forms. The second sentence is arguably redundant with the idempotency annotation, but the overall size is tight.

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, non-destructive mutation with full schema coverage and annotations declaring safety, the description is nearly sufficient. It omits any note on effects (e.g., notification to the target) but nothing essential for correct invocation is missing.

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%: 'actor' is documented as handle-or-DID and 'account' explains the acting account with a pointer to list_accounts. The description's 'by handle or DID' adds no meaning beyond the schema, so the baseline 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?

States a specific verb and resource ('Follow an account'), and clarifies the accepted identifier forms. It does not name the sibling it contrasts with (unfollow) or scope the side effects, so it is clear but not fully differentiated from siblings in prose.

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?

'Following twice is harmless' hints at safe repeated use, but there is no guidance on when to follow versus related tools like get_suggested_follows or search_actors, nor any prerequisites. Usage is only implied rather than spelled out.

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

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

Annotations already cover read-only/idempotent/open-world safety, and the description adds genuinely new behavioral facts: it works with or without credentials, and results are returned newest first. It stops short of describing pagination or result volume beyond what the schema says.

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

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

Three short sentences, front-loaded with the core scope and ordering before secondary auth and filter advice. No filler or restated title 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?

For a 7-parameter read tool with annotations but no output schema, the description covers scope, ordering, auth mode, and the most semantically loaded parameter. Remaining gaps (e.g., pagination, time-window behavior) are largely covered by the schema descriptions.

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 86%, so the structured fields already carry the parameter burden. The description only adds intent-level color for the filter param ('is what you want when studying how someone writes') and does not touch actor, limit, cursor, since_hours, or include_pins.

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

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

States a specific verb and resource ('Posts by one account') plus ordering ('newest first'), which cleanly separates it from siblings like search_posts, get_feed, and get_timeline. An agent can identify the tool's scope without opening the schema.

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 auth context ('Works for anyone, with or without credentials') and steers the filter choice toward 'posts_no_replies' for authorship analysis. However, it never states when to prefer this tool over get_timeline or search_posts, so the competitive routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered and the bar is lower. The description adds that this is an aggregating read (totals/averages) rather than a raw listing, which is useful context. It says nothing about cost, rate limits, or whether reading many posts is expensive.

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 first sentence is dense and front-loaded with the useful content. The second sentence ('Bluesky offers no equivalent') is a comparative aside that is confusing in a Bluesky-targeted toolset and does not help an agent invoke the tool, so it fails to earn its place.

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

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

For a read-only summary tool with full schema coverage and complete safety annotations, the description is largely sufficient, and it even sketches the return shape (totals, averages, rate, per-format breakdown) despite no output schema. Missing only explicit routing against sibling analytics tools.

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

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

Schema description coverage is 100%, so days, actor, limit and account are all documented in the schema already. The description adds no syntax, format, or defaulting nuance beyond that. Baseline 3 is appropriate when the schema carries the full parameter burden.

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

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

States a specific verb and resource and spells out exactly what is computed: totals, averages, engagement rate, broken down by format. That level of detail lets an agent distinguish it from aggregation-flavored siblings like get_post_stats or rank_posts. The trailing 'Bluesky offers no equivalent' claim is odd and potentially misleading given every other tool clearly targets Bluesky accounts.

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

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

Usage is only implied via the phrase 'so you can see whether images or video actually earn their effort,' which conveys the analyzing intent. It never states when to prefer this over rank_posts or get_post_stats, nor any prerequisite (e.g. that it defaults to the connected account). Adequate but leaves selection to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds no behavioral detail of its own - nothing about paging, rate limits, or what happens with an invalid feed URI - so it contributes essentially nothing beyond the structured fields.

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

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

Two short sentences with no wasted words; the core action and the required identifier format are front-loaded, and the follow-up sentence is pure routing value.

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

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

For a read-only listing tool with complete annotations and no output schema, the description plus schema cover what an agent needs to call it. The only notable gap is that `cursor` carries no description anywhere, leaving the paging mechanism only half-explained.

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 75%, so the schema already documents `feed` (URI or link), `limit` (max 300, pages automatically, default 30) and `account`. The description merely restates the accepted `feed` formats and says nothing about `cursor` or pagination beyond what the schema states, so the 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?

Specific verb (Read) plus resource (posts from a custom feed), and it names the accepted identifier formats (at:// URI or bsky.app link). It also implicitly distinguishes itself from sibling feed tools (search_feeds, get_pinned_feeds, get_list_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?

It explicitly routes the agent to search_feeds for discovering a feed and get_pinned_feeds for the caller's own feeds, which is the key prerequisite for invoking this tool. It does not, however, contrast itself with other post-reading siblings like get_timeline or get_list_posts.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds key behavioral detail: results are sorted newest first, and pagination automatically handles Bluesky's 100-item ceiling. This goes beyond annotations.

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

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

Two concise sentences that front-load the resource and include a key pagination note. 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 no output schema, the description covers ordering and pagination behavior, which are crucial. It omits mention of cursor usage, but the schema covers that. Nearly 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 75%, so most parameters are documented. The description doesn't add format or constraints beyond what the schema provides (e.g., actor as handle/DID, limit default). Baseline 3 is appropriate when schema does 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?

States a specific verb (list) and resource (followers of a given account) with clear scope. Distinguishes from siblings like get_follows (the inverse) and search_actors by specifying 'Accounts that follow a given account'.

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

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

Implies use for retrieving followers, but does not explicitly state when to use this versus alternatives like get_follows (the inverse). Still clear enough for an agent to infer from the description and name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds one genuine behavioral fact, automatic pagination, which is not in the annotations. It says nothing about result size limits or what happens to the cursor param when paging is automatic, leaving a gap.

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

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

Two short sentences with zero filler, and the resource is stated before the pagination note. It is terse to the edge of under-specification, but nothing is wasted.

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

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

For a simple read tool the annotations cover safety, but with no output schema the description should at least hint at the return shape (a list of account records). It covers the operation and pagination but leaves return values and the cursor/auto-page interaction to inference.

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

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

Schema coverage is 75% and the two most important params (actor, account) are documented in the schema itself. The description adds no meaning beyond the schema and does not clarify the tension between automatic paging and the exposed cursor parameter. Baseline 3 is appropriate.

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

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

The noun phrase 'Accounts a given account follows' names the resource and its direction (the inverse of get_followers), but there is no explicit verb and no differentiation from the close sibling get_relationships or get_followers. The agent must infer that this is a list operation from the title.

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

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

No when-to-use guidance and no mention of alternatives, despite get_followers and get_relationships sitting right next to it in the toolset. The direction of the relation is implied but never stated as a selection criterion.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, open-world), so the description's added value is the ordering guarantee and the hard scoping limitation tied to a platform constraint. It adds real context beyond the structured fields, though pagination behavior via cursor is left unaddressed.

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

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

Two sentences with zero filler, front-loading what the tool returns before the constraint that limits it. Every clause earns its place.

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

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

For a read-only listing tool with no output schema, the description covers scope, ordering, and the main failure condition. The unmentioned cursor/pagination semantics are a minor gap that the caller can infer from the schema.

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

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

Schema coverage is 67%: limit and account are described in the schema, cursor is not. The description adds no parameter-level detail at all, so it neither compensates for the undocumented cursor nor enriches the documented ones. Baseline 3 is appropriate given the schema does most of the work.

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

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

States a specific verb+resource ('Posts a connected account has liked') plus ordering ('newest first'), so an agent knows exactly what it retrieves. It does not name a sibling, but the scoping rule implicitly separates it from tools like get_post_likes that read likes on a given 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?

Gives a clear applicability rule: only for your own accounts, with the reason ('Bluesky does not expose anyone else's likes as a feed'). That tells the agent when the call will fail, though it never names an alternative tool for other sources.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: no pagination behavior, no ordering, no note about lists that fail to resolve or the handling of a malformed at:// URI.

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

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

It is short, but the brevity reflects under-specification rather than tight writing — a single fragment with no front-loaded verb or scope. There is no wasted sentence, but there is almost no sentence at all.

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 four-parameter, read-only, paginated endpoint with no output schema, the description should at minimum explain the cursor/limit pagination loop and what each returned account entry represents. None of that is present, and one parameter is undocumented even in the schema.

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

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

Schema coverage is 75%: list, limit, and account are documented in the schema while cursor is not. The description contributes zero parameter meaning on top of that, leaving the pagination parameter entirely unexplained in both places and offering no format examples beyond what the schema already gives.

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

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

The description 'The accounts on a curated list.' is a noun fragment that essentially restates the tool name and title without a verb. 'Curated list' hints at Bluesky list semantics, but an agent gets no confirmation of what operation is performed or how it differs from siblings like get_lists or 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as search_actors, get_follows, or get_list_posts. The agent must infer from the name alone that this is the way to enumerate membership of an already-known list.

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

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

Annotations already establish the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), so the description only needs to add beyond that, and it does by disclosing the 'newest first' ordering. It says nothing about how cursor-based pagination terminates or how large the default page is beyond what the schema states.

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

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

Two tight sentences, with the resource and ordering front-loaded and the input-sourcing hint second. No redundant restatement of the name or title.

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-feed reader with no output schema, the description covers scope, ordering, and where the required argument comes from, which is sufficient to call it correctly. Cursor/pagination behavior is the only meaningful omission, and that is minor here.

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

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

Schema coverage is 75%, so the schema documents most fields, but the description still adds value by naming the source of the list URI (get_pinned_feeds or a link), which the schema does not. It leaves 'cursor' entirely to the schema and adds no detail on limit/account defaults.

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

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

States a concrete resource ('posts from the accounts on a curated list') plus a sort order ('newest first'), which is enough for an agent to tell it apart from get_timeline, get_feed, and get_author_feed by scope. It does not explicitly name those siblings, so it stops short of a 5.

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

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

Gives a real prerequisite for the required parameter by pointing to get_pinned_feeds or a bsky.app /lists/ link, which is actionable routing rather than generic filler. It offers no when-not-to-use guidance versus the other feed tools, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results carry a URI consumed by other tools, but says nothing about pagination behavior, ordering, or the authenticated-account requirement beyond what the schema already states.

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

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

Two short sentences with no filler, and the resource being returned is front-loaded before the follow-up tool routing. It reads as an elliptical noun phrase rather than a full sentence, which is a minor structural weakness but costs the agent nothing.

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

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

With no output schema, the description does the necessary work of explaining that the return value is a set of lists whose URI feeds other tools, and pagination is documented in the schema. For a simple paginated read tool this is nearly complete; ordering and empty-result behavior are the only 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% (actor = handle or DID, limit 1-100, cursor continuation, account selection), so the schema carries parameter meaning on its own. The description adds no parameter-level detail such as default limit or what happens when the account has no lists, so baseline 3 applies.

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

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

States the resource precisely ('curated lists an account has created') and scopes it to one actor, so an agent can distinguish it from feed/post retrieval tools. It lacks an explicit verb and does not explicitly contrast with any sibling, but the resource noun plus the routing to get_list_posts/get_list_members makes intent 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?

Usage is implied rather than stated: fetch an account's lists, then use the returned URI with get_list_posts or get_list_members. This is downstream chaining advice, not when-to-use-this-vs-an-alternative guidance, and there are no exclusions or prerequisites (e.g., that `account` selects the acting identity).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds ordering (newest first) and the actionable-reason heuristic, but says nothing about pagination behavior or auth needs beyond what the schema provides. Reasonable but not rich.

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

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

Two sentences, front-loaded with the resource and ordering, followed by the filtering heuristic. Slightly informal ('a person actually has to deal with') but no real waste.

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

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

No output schema exists, but the description conveys what is returned (notification types, newest first) and how to narrow results. Combined with annotations covering safety and a schema that documents pagination and account selection, it is largely complete; missing explicit mention of pagination or unread filtering.

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 80%, so the baseline is 3. The description adds semantic value by indicating which 'reasons' enum values are most actionable ('mention', 'reply'), which is meaning beyond the raw enum list. It does not address limit, cursor, account, or unread_only.

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

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

States a specific resource (notifications) and its scope: likes, reposts, follows, mentions, replies, quotes, newest first. An agent can identify it as the notifications reader. It does not, however, distinguish itself from siblings like get_unread_count or mark_notifications_seen.

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?

Offers actionable guidance on filtering: use 'mention' and 'reply' to surface items that need an answer. That covers a key usage pattern, but there is no statement of when to use this tool versus get_unread_count or mark_notifications_seen, so the routing guidance is incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds useful ordering behavior and the fact that returned values are URIs consumable by other tools, but says nothing about pagination, empty results, or how many pins to expect.

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

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

Two short sentences with no filler; the resource and its scope come first and the follow-up routing second. Nothing could be removed without losing 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?

With no output schema, the description does convey the return shape (feeds and lists, ordered, as URIs), which is the key missing piece an agent would otherwise have to guess. Minor gap: no indication of result volume or what an empty pin set looks like.

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

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

Only one optional parameter and schema description coverage is 100%, so the schema already documents the 'account' handle semantics, the default behavior, and the list_accounts pointer. The description contributes nothing beyond that, which is the baseline expectation at full 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?

Names a specific resource (the feeds and lists pinned to a connected account's home screen) with an implicit list verb and adds the ordering scope ('in order'). It is clearly distinguishable from get_feed, get_lists, and search_feeds, which cover non-pinned or single-item retrieval.

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

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

States the downstream action explicitly: 'Pass any of the returned URIs to get_feed or get_list_posts,' which routes the agent to the correct follow-up tools. It does not, however, state when to prefer this over siblings like get_lists or search_feeds (e.g., only when pinned content is wanted), leaving that to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the useful fact that results are derived from the user's own account rather than a generic benchmark, but it omits defaults and sampling bounds (90-day window, 500-post read cap) that materially affect results.

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

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

A single sentence with no filler, and it front-loads the output shape before revealing the payoff orientation. Every clause earns its place.

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

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

For a five-parameter, read-only tool with no output schema, the description conveys the essential return shape (engagement grouped by hour and weekday). It stops just short of being fully complete by not surfacing default windows or that results are limited to the most recent N posts.

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 all five parameters are already documented in the schema, including actor, account, timezone_offset_hours and limit. The description adds no parameter-level syntax or format detail beyond what the schema provides, so the baseline 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?

States a specific resource (your posting times crossed with earned engagement) and the exact aggregation (by hour and by weekday), and frames the question it answers ('when should I post'). This cleanly distinguishes it from sibling analytics tools like get_engagement_summary or get_post_stats, which report aggregate engagement without the time-of-day/weekday breakdown.

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

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

Usage is implied by the framing question 'when should I post', so an agent can infer the context. However, it never names alternatives (e.g., get_engagement_summary, get_post_stats) or states when NOT to use this tool, leaving the agent to guess how it differs behaviorally from the other analytics siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered without the description. The description adds one genuine behavioral fact beyond the structured fields — results are returned 'newest first' — but omits anything about pagination behavior or result shape.

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

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

A single short sentence fragment with zero waste and the key scoping facts (accounts, specific post, ordering) front-loaded. It is arguably too terse to be maximally useful, but nothing is padded or repeated.

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?

This is a simple read-only list tool with no output schema and full schema coverage, so the description needn't explain return fields. Still, it says nothing about pagination despite exposing limit/cursor, and nothing that separates it from its inverse sibling get_liked_posts — an agent could easily pick the wrong one.

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 all four parameters (uri, limit, cursor, account) are already documented in the schema, including the account fallback and cursor semantics. The description adds the ordering of results but no parameter syntax or format detail beyond what the schema provides, so the baseline 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?

The description names the specific resource — the accounts that liked a given post — which is unambiguous enough for an agent to identify the operation. However, it is a noun fragment with no explicit verb, and it does not distinguish itself from the easily-confused sibling get_liked_posts (the inverse direction: posts a user liked).

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?

There is no guidance on when to use this tool versus alternatives such as get_liked_posts, get_reposted_by, or get_quotes, nor any stated prerequisites. The agent must infer usage purely from the tool name and the phrase 'liked a specific post.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without the description. The description adds no behavioral detail beyond that – no note on whether it aggregates counts versus returning actor lists, and no rate-limit or auth context. With the annotation bar lower, this is minimum-viable.

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

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

Two short sentences, zero filler, with the returned data front-loaded and the sibling relationship last. Nothing repeats the title or wastes space.

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

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

With no output schema, the description usefully enumerates the metrics returned, which is what an agent needs. The one residual ambiguity – whether these are aggregate counts or actor records, especially given sibling get_post_likes – is minor but real.

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 uri parameter already documents 'A bsky.app link or an at:// URI' and the account parameter explains account selection and defaults. The description's 'by URL or at:// URI' simply restates the schema, so the baseline 3 is correct.

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?

It names the exact data returned (likes, reposts, replies, quotes) and the resource (a single post), and it orients the agent against a sibling by calling itself 'the one-post version of rank_posts.' The verb is implicit in a noun phrase rather than stated, and it never distinguishes itself from single-metric siblings like get_post_likes or get_quotes, so it falls short of a 5.

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

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

Usage is only implied: the 'one-post version of rank_posts' phrasing suggests it is the single-post counterpart of a multi-post ranking tool. There is no explicit when-to-use, no exclusion against the overlapping siblings (get_post_likes, get_quotes, get_reposted_by), and no precondition noted.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds the returned-content scope (ancestors plus replies), which is useful, but says nothing about pagination, truncation at depth limits, or rate behavior. With annotations carrying the safety profile, this is adequate but not rich.

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

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

Two sentences, zero filler. The scope-defining clause comes first and the usage directive follows, so the agent gets purpose before 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?

For a read tool with full schema coverage and a complete annotation set, the definition covers purpose, input format and usage timing. Since there is no output schema, a sentence sketching the shape of the returned thread (e.g., root/post/parent/replies fields) would have closed the remaining gap.

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

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

Schema description coverage is 100%, so uri, depth, account and parent_height are already documented in the schema, including the at:// / bsky.app link forms and defaults. The description adds no parameter detail beyond that, which is the correct baseline 3 when 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?

The description uses a specific verb ('Read') and defines the resource precisely: a post plus 'everything above it and the replies below.' That scope statement inherently differentiates it from siblings like get_feed, get_quotes, or get_post_likes, which return different slices of conversation 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?

It gives explicit usage timing: 'Use this before replying, so the reply lands with context.' That is clear context for when to call it. It does not name alternatives (e.g., get_quotes for quote posts, search_posts) or state when-not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: it works without credentials, and follow/follower-relationship data is only present 'when a connected account is available' – a conditional result shape the agent would otherwise not anticipate.

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

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

A single front-loaded sentence delivers the resource, the returned fields, and the conditional behavior, followed by a two-word credential note. No filler, no repetition of the title.

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 annotations carrying the safety profile and no output schema required, the description covers the essentials: scope, returned fields, credential independence, and conditional relationship data. It stops short of noting behavior for invalid handles or how many profiles are returned per call, but these are minor omissions for a read tool.

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

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

Schema coverage is 100%, with both the actors array (handles/DIDs, up to 25) and the account selector fully documented in the schema. The description only echoes the batch nature ('one or more accounts') and hints that the account parameter drives the follow-relationship enrichment; it adds little syntax or format detail 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 names a specific resource (profile) and enumerates exactly what it returns: bio, follower counts, labels, and relationship status. It is clearly distinguishable from siblings like search_actors (discovery) and get_followers (list retrieval) because it returns a per-account profile bundle.

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

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

It provides one genuinely useful usage cue – 'Works without credentials' – which tells the agent this call is available even in an unauthenticated context. However, it never states when to prefer this over search_actors, get_relationships, or whoami, so routing guidance is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description instead adds a semantic distinction about quotes vs reposts, which is useful context but not behavioral disclosure (no pagination, rate-limit, or return-shape notes).

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

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

Two short sentences, front-loaded with the resource definition and followed by the differentiating commentary. Zero filler.

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

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

For a read-only paginated query with full schema coverage and annotations covering the safety profile, the description supplies enough to call it correctly. No output schema exists, but the return concept (quote posts) is reasonable to infer; only minor gaps remain.

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

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

Schema description coverage is 100% (uri, limit, cursor, account all documented with examples), so the baseline is 3. The description adds no parameter-level detail such as URI format or pagination behavior beyond what the schema already states.

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

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

The description states the resource precisely — 'Posts that quote a specific post' — and contrasts it with reposts, so an agent can distinguish the concept from a sibling like get_reposted_by. It stops short of naming the retrieval verb or the sibling tool explicitly, so it is clear but not fully differentiated.

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

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

It gives a genuine usage signal: 'This is where the argument about a post usually lives: quotes carry commentary, reposts do not,' which tells the agent to reach for this when the user wants discussion/commentary. It does not name the specific alternatives (get_reposted_by, get_post_likes) or state exclusions, so no 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuine behavioral context: it is a single batch call covering a whole list, and it discloses the two-directional result (follows / follows back) that the agent will receive, which matters since there is no output schema.

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

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

Three short sentences, front-loaded with the core behavior and then the routing guidance. Minimal waste; the only blemish is the opening fragment, which reads slightly awkwardly but stays 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?

For a read-only tool with no output schema, the description usefully explains the shape of the result (per-account follows/follows-back booleans) and the batch scope. Nothing critical is missing, though it could note the 30-account cap or auth expectations.

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 both parameters are already documented in the schema. The description implies the 'actors' list ('for each account named') and the acting account ('a connected account'), but adds no format or syntax detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific operation: for each named account, report whether a connected account follows them and whether they follow back. This distinguishes it from siblings like get_profile and get_followers by being a batch, bidirectional relationship check. The first sentence is a sentence fragment, but the meaning is clear.

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

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

Gives explicit when-to-use guidance ('before a bulk follow or unfollow') and names an alternative to avoid ('rather than reading a profile each time', i.e. get_profile). It does not state a when-not condition (e.g. for a single account), so it falls just short of full routing 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds nothing behavioral on top of that — no pagination behavior, no empty-result behavior, no rate/visibility caveats.

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

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

A single short fragment with no waste, but it is under-specified rather than truly concise — the brevity comes from omission of any actionable detail. Front-loading is moot when there is only one clause.

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?

No output schema exists, so the description would ideally hint at the return shape (a paginated list of account objects with cursor) — it does not. Given the simple read-only nature and complete schema coverage, a minimum-viable 3 is appropriate but gaps remain.

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

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

Schema description coverage is 100%, so all four parameters (uri, limit, cursor, account) are documented in the schema itself. The description contributes no additional parameter meaning, which is the expected baseline of 3 when 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?

The description identifies the resource (accounts that reposted a given post) but is a bare noun phrase with no verb, and it largely restates the tool name 'get_reposted_by'. It does not distinguish itself from siblings like get_post_likes or get_quotes beyond the word 'reposted'.

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?

There is no guidance on when to use this tool versus alternatives such as get_post_likes, get_quotes, or get_post_stats. No prerequisites, no mention of needing a valid post URI or an authenticated account context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the mode-dependent behavior (actor changes what the result set means), but says nothing about rate limits, pagination, or whether results are personalized per connected account.

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

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

Two short sentences with the primary behavior front-loaded and the actor distinction immediately following. The trailing clause about finding a niche is slightly editorial but earns its place as the only usage hint present.

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, three-optional-parameter tool with no output schema, the description covers what is returned and how the actor parameter changes it. It could still say more about result ordering or the connected-account dimension, but nothing essential is missing.

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 all three parameters are already documented, including the actor semantics and the 'omit for suggestions for you' default. The description restates the actor behavior without adding format, ranking, or quality details beyond the schema — baseline 3.

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

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

States a specific resource (suggested follow accounts) and clarifies the two operating modes: default 'suggestions for you' vs. actor-seeded 'similar accounts'. It is distinguishable from search_actors, but it never names that sibling, so the differentiation is implicit rather than explicit.

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 phrase 'which is the better way to find a niche' hints at when the actor mode is preferable, but there is no explicit when-to-use guidance, no when-not, and no named alternative (e.g., search_actors) for discovery tasks. Usage is implied rather than directed.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful non-annotation context: newest-first ordering and the authentication requirement ('Requires a connected account'). It does not mention pagination limits or rate limiting, but the essential behavior is disclosed.

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

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

Three short sentences, zero filler, with the identity of the feed and the ordering front-loaded before the parameter hint. Every sentence carries information.

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

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

For a read-only tool with full annotations and complete schema documentation, the description covers what it returns (following feed, newest first), how to scope it, and the auth prerequisite. The absence of an output schema is not a problem since the return shape is obvious, but cursor/pagination behavior is left entirely to the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description explains the since_hours/limit tradeoff at a high level, but the schema already documents that tradeoff in more detail ('Instead of a fixed count... up to `limit`'), so the description adds little beyond the structured fields.

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

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

States a specific resource ('Your following feed') and an ordering guarantee ('newest first'), which distinguishes it from author/list feeds. It never names a sibling such as get_feed or get_author_feed, so the agent must infer which feed tool is the home timeline from the phrase alone.

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?

'Pass since_hours to read a time window rather than a fixed number of posts' gives clear guidance on parameter selection and 'Requires a connected account' states a prerequisite. However, it offers no guidance on when to choose this tool over get_feed, get_list_posts, or get_author_feed, which are all feed-reading siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior. The description adds two useful facts beyond them: no credentials are required, and each result carries a feed link exposing the underlying posts.

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

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

Two short sentences, front-loaded with the resource and immediately followed by the return shape and the auth note. No filler.

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

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

With no output schema, the description usefully characterizes the return value (topics plus feed links) and the auth posture, and annotations cover the safety profile. Minor gaps: nothing about result count default or ordering is stated here, though the schema covers limit.

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 limit, account and include_suggested are fully documented in the schema itself. The description adds no further parameter meaning, so the baseline 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?

States a specific verb+resource ('current trending topics on Bluesky') and clarifies the payload ('each with the feed link that shows the posts behind it'). No sibling tool covers trends, so an agent can route here unambiguously.

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

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

The description implies when to use it (you want to see what is trending) and notes it works without credentials, but offers no explicit when-not guidance or alternatives among siblings. Adequate but minimal.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the count window is anchored to the last 'mark seen' action, and it characterizes the call as low-cost. Return format/pagination is not discussed, but the tool is a trivial read.

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

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

Two short sentences, zero waste, with the counting semantics front-loaded and the usage cue second. Nothing to trim.

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 one-optional-parameter read with no output schema, the description covers what is counted and why to call it. It could note that the result is a plain integer, but nothing critical to correct invocation is missing.

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% and the single 'account' parameter is fully documented with its default and a pointer to list_accounts. The description adds nothing about parameters, so the 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?

States a specific quantity (how many notifications) and the scope that makes it distinct: 'since you last marked them seen.' This separates it from get_notifications and mark_notifications_seen without naming them, but the distinction is inferable from the phrasing.

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?

'Worth making before you pull the full list' gives an explicit ordering cue relative to the heavier get_notifications sibling, and 'one cheap call' signals cost. It stops short of naming the alternative tool outright or stating when the count is not useful.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context: the job self-completes, so polling is rarely necessary, and the id originates from a prior create_post timeout message. It does not describe the shape of the status response, which is the remaining gap.

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

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

Three short sentences, zero filler, and the triggering condition is front-loaded right after the purpose. Every sentence carries actionable information.

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

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

For a simple read-only status check with no output schema, the description covers purpose, trigger condition, and id provenance. The one omission is what the returned status actually looks like (e.g. whether it reports progress, success, or failure), which the agent would have to discover at runtime.

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 both parameters are already documented, including the account/handle convention and the list_accounts pointer. The description's note that the id comes from the create_post message largely duplicates the job_id schema description, so it adds little beyond the baseline.

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

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

States a specific verb and resource ('Check a Bluesky video transcoding job by id'), which is clearly distinct from every sibling tool, most of which are social-graph or feed operations. An agent can immediately tell this is a job-status poller.

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 scopes when this tool is needed ('Only needed when create_post reported that a video was still processing when it gave up waiting') and even discourages unnecessary use ('The job usually finishes on its own'). It also tells the agent where the required id comes from, which is a routing detail no other field provides.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description nevertheless adds concrete behavioral detail beyond the hint: on a repeat like, the existing like object is returned instead of creating a duplicate, which is useful since there is no output schema.

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

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

Three short sentences, zero filler, with the core action front-loaded before the input formats and the idempotency note. 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?

For a two-parameter, fully documented write tool with idempotency annotations, the description covers action, accepted inputs, and duplicate behavior. The lack of an output schema is partly compensated by the note about what a repeat like returns; only account/auth behavior is left to the schema.

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

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

Schema description coverage is 100%, so both the uri and account parameters are already fully documented in the schema. The description's mention of accepted URI formats duplicates the schema's own wording and adds no new syntax or format 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?

The description states a specific verb and resource ('Like a post') that an agent can immediately match to the like_post tool and distinguish from unlike_post/repost. It does not explicitly name those siblings, but the single-purpose verb makes the boundary 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?

Usage is implied by the tool's single obvious purpose, and the accepted URI forms are noted, but there is no explicit guidance on when to like vs. alternatives (repost, get_post_likes) or on prerequisites such as authentication/account selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile needs no restating. The description usefully adds that the server can act as multiple accounts, but says nothing about output shape or ordering beyond what the annotation set covers.

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

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

Three short sentences, front-loaded with the purpose, then the downstream usage, then the trigger condition. No filler or repetition.

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?

No output schema exists, yet the description makes clear what the result is (account handles) and what to do with it. For a no-parameter, read-only discovery tool, nothing an agent needs is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline is 4. The note about the returned handle being reused as an `account` argument elsewhere is a helpful cross-tool hint.

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

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

States a specific verb and resource ('List every Bluesky account this server can act as') with a clear scope constraint that distinguishes it from siblings like whoami (self) and search_actors (search). An agent knows exactly what comes back.

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?

Gives explicit when-to-use ('call this first when the user has more than one account and has not said which one they mean') and explains how the result feeds other tools ('use the handle from here as the account argument on any other tool'), which is actionable routing 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 non-destructive, idempotent, and open-world, and the description adds genuinely new behavioral context: the effect is bulk ('every notification up to now'), it resets the unread count, and the visibility scope is private ('affects only your own view, and nobody else can tell'). That scope/privacy disclosure is exactly the kind of thing annotations cannot convey.

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 tight sentences with the effect front-loaded and the privacy caveat second; nothing is wasted and no filler.

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

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

For a two-optional-parameter mutation with no output schema and annotations covering safety, the description supplies what the structured fields cannot: the bulk scope and privacy semantics. It omits error behavior and how the account parameter resolves, but those are minor for a tool this simple.

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 both parameters (account, seen_at) are already fully documented. The description's 'up to now' loosely corroborates seen_at's default-to-now behavior but adds no syntax or format detail. 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?

States a specific verb and resource ('mark every notification up to now as seen') plus the observable effect ('unread count resets'). It is clearly distinguished from read siblings like get_notifications by describing the mutation, though it does not name any sibling explicitly.

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

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

The use case is implied by 'so the unread count resets', but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as get_notifications or get_unread_count. Adequate but leaves routing to inference.

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

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

Annotations cover the safety profile (destructiveHint=false, idempotentHint=true) but say nothing about visibility or reversibility. The description adds two traits the annotations cannot express: the action is private ('without them knowing') and reversible, plus the concrete post-mute relationship state. It omits any note about what the target sees or required scopes, but the added behavioral value is real.

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

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

Three short sentences, no filler, and the core effect plus its privacy guarantee are front-loaded ahead of the block comparison.

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 two-parameter, no-output-schema action tool with full annotation coverage, the description supplies the effect, privacy property, reversibility, and sibling contrast. The only gap is that it does not name unmute_account as the undo path, which the 'reversible' claim naturally invites.

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% for both parameters, and the 'account' parameter even documents the list_accounts discovery path. The description adds no syntax or format detail beyond the schema, so the baseline 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?

The description gives a specific verb (hide/mute) applied to a specific resource (an account's posts) and states the effect scope ('from your feeds'). It also explicitly names and contrasts with the sibling block_account, so an agent can distinguish it from adjacent tools without reading schemas.

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?

'Unlike a block, they can still see and reply to you' tells the agent when to prefer mute over block, which is the key sibling decision. It stops short of stating when-not-to-use or pointing at unmute_account for reversal, but the selection context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful framing that this data is not surfaced natively ('Bluesky shows you none of this'), but says nothing about ordering stability, rate limits, or scoring methodology.

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

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

Three short sentences, front-loaded with what the tool returns, then usage hints. No padding, though the phrasing 'Your posts, best first' is a little informal and the phantom 'format' clause wastes a clause.

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

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

For a zero-required-parameter read tool with full schema coverage and no output schema, this is adequate: it names the returned metrics and the two most nuanced parameters. But the non-existent 'format' parameter leaves a real ambiguity about what the output can be filtered or shaped by.

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 all five parameters are already documented and the baseline is 3. The description reinforces days but references a 'format' option that does not exist in the schema, which adds confusion rather than meaning.

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

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

States a concrete verb and resource (rank your posts by engagement) plus the payload returned (likes, reposts, replies, quotes), which is more specific than the bare title. It doesn't explicitly differentiate itself from close siblings like get_engagement_summary or get_post_stats, so it stops short of a 5.

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

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

Offers real usage guidance for two parameters, telling the agent to use days to score a period rather than a fixed count and format to compare media types. However, it names no alternative tool or exclusion, so the agent must infer when rank_posts beats get_engagement_summary or get_author_feed.

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

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

Annotations already declare destructive=false, idempotent=true, readOnly=false, openWorld=true. The description adds a concrete behavioral fact beyond them: 'Reposting twice is harmless,' which reinforces the idempotency hint in plain language. It does not cover auth or rate limits, but the annotations carry the safety profile.

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

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

Three short sentences, front-loaded with the action, followed by the idempotency reassurance and the alternative-tool routing. No waste.

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

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

For a simple two-parameter mutation with full schema coverage and annotations covering safety and idempotency, the description is complete enough to call correctly. No output schema exists, but the tool returns little that needs explaining. Minor gap: no mention of what happens if the post is already reposted vs. this being harmless.

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 both parameters are already documented in the schema, including the account default and the list_accounts reference. The description adds no parameter detail beyond what the schema provides, so the 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?

States a specific verb (repost) and resource (a post), and clarifies the effect: it goes to your followers. It explicitly distinguishes itself from create_post with quote, so an agent can tell it apart from the sibling that produces a comment-bearing repost.

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?

Gives explicit routing: use this to repost, use create_post with `quote` when you want to add a comment. That is a when-to-use-this-vs-alternative instruction, not mere inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds two things annotations cannot: the no-credential auth requirement and the shape of what comes back (bio, follower counts). Pagination behavior via cursor is left unstated.

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

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

Three short sentences, no filler, with the core capability front-loaded and the practical payoff (spotting impersonators) last. 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?

With no output schema, the description usefully discloses the return fields, and it covers the credential requirement. It omits pagination semantics for cursor, which is the only meaningful gap for a search tool of this size.

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

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

Schema coverage is 75% and the q parameter is already documented as "Name, handle or keyword". The description adds only marginal value by naming "bio text" as a searchable surface; limit, cursor and account are untouched. 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?

States a specific verb (Find) and resource (Bluesky accounts) plus the searchable fields (name, handle, bio text). Clearly separable from siblings like search_posts, search_feeds and get_profile without opening any schema.

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?

"Works without credentials" gives a concrete precondition an agent can act on, and the impersonator use case implies the intended scenario. However, it never names alternatives (e.g. get_profile for a known handle) or states when not to use this search.

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, openWorldHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds real value beyond that by disclosing that no credentials are needed, an auth trait the annotations do not express. It says nothing about pagination or result ordering, which keeps it from a 5.

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

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

Three short sentences with no filler: identity of the resource first, the follow-up action second, the auth condition last. Every sentence carries information an agent needs.

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-only search with full schema coverage and no output schema, the definition covers what the tool is, how to use its result, and its auth requirements. Only result shape/pagination behavior is unaddressed, a minor gap for a 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 description coverage is 100%, so q, limit and account are already documented with examples and defaults in the schema itself. The description adds no syntax, format, or constraint detail beyond that, so the 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?

States a specific verb (Find) and resource (custom feeds) and then defines the resource inline as 'the algorithmic feeds anyone on Bluesky can publish', which separates it from search_posts and search_actors in the sibling 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?

Gives a clear downstream workflow ('Pass a feed's URI to get_feed to read it') and a precondition ('Works without credentials'), which is genuine when-to-use context. It does not contrast against alternatives like get_pinned_feeds or get_trends, so it stops short of full routing 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 readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond them: the connected-account requirement and the fact that the public unauthenticated API rejects this endpoint. It stops short of describing result ordering or paging behavior.

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

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

Three sentences, purpose and scope front-loaded, then capability and prerequisite. The operator list is long but each item is directly usable; no filler 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?

The tool has no output schema and eight parameters, yet the description says nothing about what a result contains (author, text, engagement) or default sort/paging behavior. Auth prerequisites and query syntax are well covered, but the return shape is left for the agent to discover.

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 88% (baseline 3), but the description goes further by enumerating the operator syntax accepted in q (from:, to:, mentions:, domain:, since:, until:, lang:, quoted phrases), which is more actionable than the schema's brief 'Operators like from:... work inside it'. Undocumented cursor is not addressed.

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

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

States a specific verb and resource with scope: 'Full-text search across public posts.' This cleanly separates it from siblings like search_actors, search_feeds, and get_author_feed without needing to open any schema.

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?

Gives a clear precondition ('Requires a connected account') and a notable constraint ('Bluesky's public API refuses this endpoint'), so the agent knows auth is mandatory. It does not, however, name alternatives (e.g., search_actors for users, get_author_feed for one author's posts) or state when-not to use it.

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

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds the non-obvious behavior that existing replies are preserved unless explicitly hidden, plus the existence of a hide-replies mode. It omits any note about permissions, reversibility of hiding, or the 300-item cap, but the core behavioral surprise is disclosed.

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

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

Three short sentences, zero filler, and the primary action plus its precondition are front-loaded before the secondary hide-replies capability.

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 four-parameter mutation tool with no output schema, the description covers what changes, when to reach for it, and the key side effect on existing replies. It could say whether hiding is reversible and whether repeated calls are safe (idempotentHint=false), which are the remaining 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 documents uri, who, account and hide_replies in detail, including the enum values and the 300 max. The description only gestures at the hide-replies capability and adds no syntax or format detail beyond the schema, so the 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?

States a specific verb and resource ('change who is allowed to reply to one of your existing posts') plus a second capability ('hide specific replies from the thread'). No sibling tool overlaps this function, so an agent can distinguish it immediately.

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?

Gives a clear situational trigger ('the main tool for a post that is going badly') and the precondition that the post is already published, which separates it from create_post/create_thread. It does not name a fallback or state when not to use it, so it stops short of explicit alternatives.

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

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

Annotations only declare the generic mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds a genuinely non-obvious side-effect caveat: follows severed by the block are not restored and both parties must re-follow. That is real value beyond the annotations, though permissions/auth requirements are not mentioned.

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

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

Three short sentences, zero filler, with the core action front-loaded and the consequential caveat immediately after. Nothing needs trimming and nothing is buried.

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 two-parameter mutation with full schema coverage and no output schema, the description covers the essential behavioral surprise (irreversible follow severance). It does not address idempotency or the multi-account selection flow, but the schema handles the latter.

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

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

Schema coverage is 100% and both parameters (actor, account) are documented in the schema, including the list_accounts pointer. The description adds no syntax, format, or default information beyond what the schema already provides, so the 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 opens with a specific verb+resource ('Remove a block'), and the tool name pairs unambiguously against the sibling block_account. It stops short of explicitly naming block_account or mute_account as related alternatives, but the operation itself is unmistakable.

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

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

Usage is implied rather than stated: the agent can infer this is the undo of block_account. There is no explicit when-to-use/when-not, no statement of prerequisites (the actor must currently be blocked), and no routing to siblings such as mute_account for a lighter-weight alternative.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds a useful behavioral detail: it locates the user's own follow record from the profile's viewer state, reducing the required input to just the handle.

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 tight sentences, front-loaded with the action and followed by a concise implementation note. No wasted words.

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

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

For a simple mutation tool with full schema coverage and safety annotations, the definition is mostly complete. The mechanism note is helpful, though it omits what happens if you are not following (partially covered by idempotentHint) and does not mention the optional account 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 description coverage is 100%, so the schema already documents both parameters. The description's note that you 'only need the handle' is a mild usability clarification but does not add new semantic 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?

States a specific verb and resource ('Stop following an account') and adds mechanism detail about finding the follow record from viewer state. The tool's identity is immediately clear and distinct from mute/block 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?

Implies usage through the action description, but does not explicitly say when to use this versus alternatives like mute_account or block_account. No exclusions or prerequisites are stated.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that by explaining the tool resolves your own like from the post's viewer state rather than requiring a like URI, which tells the agent how the call behaves internally.

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

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

Two short sentences, zero waste, with the action front-loaded and the argument-saving clarification second. Nothing could be cut without losing information.

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

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

For a low-complexity, two-parameter mutation with full schema coverage and annotations covering safety and idempotency, and no output schema to explain, the description addresses the only non-obvious aspect (which identifier to supply). Nothing an agent needs to call it correctly is missing.

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% and both parameters are documented in the schema, so baseline is 3. The description only reinforces that the like identifier is unnecessary, adding marginal meaning over the schema's own uri 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?

States a specific verb and resource ("Remove your like from a post") that is unambiguously distinct from sibling like_post and repost/unrepost. The second clause clarifies the operation's mechanism, removing any ambiguity about what record is targeted.

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 undo-a-like context is implied by "Remove your like," and it usefully notes you need only the post, not a like identifier. However, it never names like_post as the inverse operation or states when-not to use it (e.g., if you have not liked the post).

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

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

Annotations already declare destructiveHint=false, idempotentHint=true, readOnlyHint=false and openWorldHint=true, so safety and idempotency are covered structurally. The description adds nothing beyond that — no statement about auth requirements, no-ops on unmuted accounts, or whether the change is reversible.

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

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

One short, front-loaded sentence with zero padding. It is efficient, though the brevity is closer to under-specification than disciplined conciseness.

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

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

For a simple state-toggle tool with complete schema coverage, no output schema and annotations covering the safety profile, the description is minimally sufficient. It omits the sibling relationship and any no-op behavior, which are the remaining 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%, including the actor format ('Handle or DID') and the account default and list_accounts pointer, so the schema carries the full parameter burden. The description contributes no additional parameter meaning, which is the baseline 3 case.

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 a concrete effect ('stop hiding an account's posts'), which is a specific verb+resource and clearly the inverse of a mute operation. It does not name the sibling mute_account, so the pairing must be inferred from the tool name alone.

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?

There is no statement of when to use this versus alternatives, no reference to mute_account as the counterpart, and no prerequisites (e.g., that the account must already be muted, or what happens if it isn't). The agent is left to infer all routing.

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