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

Annotations already declare readOnlyHint and idempotentHint, so the read-only nature is covered. The description adds behavioral context beyond that: it can read a run's progress while running, and it explicitly requires a free Prowlo account, which is a precondition. There is no contradiction with annotations, and no unexpected side effects are implied.

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 dense but well-structured, using backticks to delineate section values and parentheticals for parameter specifics. It packs a lot of information (sections, defaults, pagination, account prerequisite) into a moderate length. It is slightly wordy, but each sentence earns its place and the structure aids readability.

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 the tool's complexity (multiple sections, pagination, run selection), the description provides sufficient context: it explains default sections, pagination by tier, progress reading, and the 'plan' section's live state. It also mentions the account requirement and where to get a signup link. While there is no output schema, the description does not need to detail return values, and the operational context is complete enough 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 descriptions cover most parameters well (83% coverage), and the description enriches them further. For example, the section parameter's enum values are elaborated with additional context (e.g., 'plan (threads carry live score/comments/removed state when available)'), and the account requirement clarifies productId/runId usage. The description adds value beyond the schema without duplicating all details.

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 reads the latest research report or a specific run, including progress while running. It enumerates the available sections (summary, communities, content, competitors, voice, plan, markdown), making the purpose unambiguous. It also distinguishes itself by instructing to read it before recommending subreddits or drafting posts/comments, which sets it apart from sibling read tools like catalog_get_subreddit or social_get_post.

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?

Explicit guidance is given on when to use: 'Read this BEFORE recommending subreddits or drafting posts/comments for the user.' It also notes the prerequisite of a free Prowlo account and directs calling it to get a signup link, which helps the agent handle missing credentials. The section parameter's meaning is spelled out, including defaults and pagination behavior, so the agent knows how to request the right data.

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