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

The description discloses the underlying semantic pipeline (AI query expansion, embedding similarity, keyword matching, precision relevance filter), which is beyond the read-only, idempotent, and non-destructive annotations. It adds meaningful behavioral context about how search works internally, though it doesn't discuss performance or limitations.

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 front-loaded with the primary purpose, then expands on the pipeline, filter stacking, and query rules in a logical order. Each sentence contributes new information without redundancy, though it is somewhat long—still efficient given the tool's complexity.

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 tool with 17 parameters and no output schema, the description covers the most critical usage pitfalls (query misuse, filter independence, when to omit query). It doesn't explain return format or pagination, but those are less critical for a read-only search tool and the annotations cover safety. Overall, it is sufficiently complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the role of the 'query' parameter (content/topic only) and warning against mixing sort/filter intent into it, plus noting that 'relevance' sort is only valid with a query. These nuances go beyond the schema definitions, earning a 4.

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

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

The description clearly states the tool searches, filters, and sorts saved Reddit posts, specifying the resource and core actions. It explains the semantic pipeline when a query is given, which adds specificity. However, it does not explicitly differentiate from the sibling tool 'semantic_search', which could overlap in function, so it falls short of full distinction.

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

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

Provides explicit guidance on query usage: use query only for content/topic matching, never for sort/filter intent, and omit it entirely for sort-only or filter-only requests. It also notes that filters stack independently. This is strong within-tool guidance, though it does not mention when to choose this tool over alternatives like semantic_search.

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