Search Reddit posts and comments

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses auth requirements (no Reddit login/API key but requires an APIFY_TOKEN), the billing model (charged per post and comment row), failure behavior (unsuccessful run returned as an error with its run ID), and the default filtering rule that discards results whose term is not in title or text. This is exactly the operational context an agent needs before invoking a paid, open-world scraper.

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 capabilities, then return shape, then defaults, then auth and billing constraints. For a 16-parameter tool the density is justified and no sentence is filler, though the single dense paragraph is slightly harder to scan than a structured list.

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 16 optional parameters and no output schema, the description carries the return-shape burden and does so: it enumerates the post row fields, the comment row behavior, and the free summary row. Auth, cost, and error semantics are also covered, leaving no material gap 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, but the description adds cross-parameter behavior the schema does not: thread URLs always return comments regardless of include_comments, and results are filtered to term-matching titles/text by default. It does not explain several other parameters such as only_new/state_key memory or max_charge_usd, so it is above baseline but not exhaustive.

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 three concrete capabilities with specific verbs and resources: keyword search across Reddit or inside subreddits, reading newest posts of a subreddit, and reading thread URLs with comments. It also states exactly what is returned (one flat row per post with named fields, one row per comment, one free summary row). An agent knows precisely what this tool does and what it produces.

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 clearly through parameter-dependent modes: search_terms alone searches all of Reddit, search_terms plus subreddits searches within them, subreddits alone reads newest posts, and thread_urls reads threads with comments. There are no sibling tools and no explicit exclusions or 'do not use when' guidance, so it falls short of a 5, but the mode routing is unambiguous.

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