rss_read

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

With no annotations, the description carries the transparency burden. It clearly signals read-only behavior by saying 'Read,' describes the returned structure, and notes the special shelf-name input. It lacks explicit error/failure semantics, but it fully discloses the core behavior and output 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?

The description is compact and front-loaded. The first sentence states the core function, followed by a useful usage note, then a clear Args/Returns structure. Every sentence earns its place with no fluff.

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

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

Given there is no output schema and no annotations, the description is remarkably complete. It documents both parameters, the return shape, and how the tool fits into a browse loop with web_read and shelf. Missing error handling is a minor gap, but the tool is simple and the description covers all essential usage context.

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

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

Schema description coverage is 0%, but the description compensates with an Args block. It defines feed_url as a full feed URL or a shelf name, which is essential extra semantics, and limit as max entries returned (default 10). This is significant value beyond the bare schema, though the limit description is somewhat minimal.

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 'Read any RSS/Atom feed: latest entries as a list,' which clearly states the verb, resource, and output shape. It also differentiates itself from siblings by positioning itself as the discovery half of a browse loop and explicitly mentioning web_read for full text.

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

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

The description explicitly explains when to use this tool: 'The discovery half of a browse loop: spot an interesting entry, then web_read its link for the full text.' It also mentions the shelf-name alternative and points to the shelf tool, providing clear context and alternatives.

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