Read a custom feed

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the pagination behavior ('Pages automatically') and the limit/cursor semantics, which are not in the annotations. However, it does not disclose the return format or whether posts include full thread context, which for a feed-reading tool could be useful but is not critical given the schema and simplicity.

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

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

The description is two short sentences, front-loaded with the core action and resource format, and the finding alternatives come after. Every sentence earns its place; there is no filler or repetition of schema fields.

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

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

The tool is a read-only list retrieval with no output schema, and the annotations already carry the safety profile. The description covers the input format, pagination behavior, and account selection, which are the main operational concerns. It lacks an explicit return-value description, but for a list tool this is minor; a 4 is generous but fair given the strong alignment with 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 coverage is 75%, meaning the feed, limit, and account parameters already have descriptions. The description adds marginal value by confirming the pagination ('Pages automatically') and tying the account parameter to list_accounts, but it doesn't add format or syntax details for the feed URI beyond what the schema says. The cursor parameter remains undocumented, but the description's mention of pagination partially compensates. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Read' with a specific resource 'posts from a custom feed' and identifies the feed by its at:// URI or bsky.app link. It distinguishes the tool from siblings like get_timeline and get_author_feed by specifying 'custom feed' and by naming the search/owned-feeds alternatives, making its scope unambiguous.

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

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

The description gives explicit context: it says to find a feed with search_feeds or get_pinned_feed, which tells an agent when this tool is appropriate and when those alternatives are better. It falls one point short of a 5 because it doesn't explicitly say when NOT to use it (e.g., for a raw timeline), but the named alternatives imply the boundary.

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