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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description still adds real behavioral context: keyset vs offset paging, 'follow next to walk everything', and a provenance disclaimer ('we index and link; the feeds belong to whoever publishes them') that tells the agent results are third-party links.

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 with the action and filter set, then dense operational detail; every sentence carries information. Slightly overloaded – the filter enumeration at the top partly duplicates the same axes later in the sentence about q/ordering – but 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 an eight-parameter, optional-only search with no output schema, the description covers ordering, both paging modes, cursor-following, retry semantics being delegated to the schema, and data provenance. Gaps: it never sketches the result shape, and it references a year filter not present in the schema, which could send an agent looking for a parameter that does not exist.

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 each parameter and the baseline is 3; the OR/AND combination rule and the filter-to-parameter mapping add marginal value. However, the description names a 'year of the newest item' filter and a 'namespace' filter that do not map cleanly (or at all) onto the eight declared parameters, which muddies rather than clarifies parameter semantics.

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

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

States a specific verb+resource ('Search the feed index') and enumerates the filter axes (format, audio/video, community, namespace, recency). It never distinguishes itself from the near-name sibling feed_find, so an agent cannot tell the two apart from the text alone, but the core purpose is unambiguous.

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

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

Gives concrete invocation rules: filters and text resolve in the same full-text query, values within one parameter are OR'd while different parameters are AND'd, and the paging/ordering model flips based on whether `q` is supplied (keyset/recent vs offset/relevance). What it does not supply is an alternative-tool call-to-action (e.g., use feed_find instead when ...), which keeps it out of the top band.

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