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

Annotations already declare readOnly/openWorld/non-idempotent, and the description adds substantial context beyond them: requires an APIFY_TOKEN, billing happens only per company whose board was found and read, no-board/blocked-board/no-readable-request cases are free, failures return an error with a run ID, and Productboard portals come back as a link. That is exactly the operational detail an agent needs before spending money.

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 core action and discovery logic, then output shape, then incremental mode, then cost/error behavior — a sensible ordering. It is a single dense block with some cramming (cost, Productboard, and error handling share one sentence cluster), but nearly every sentence carries information an agent would otherwise lack.

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 13-parameter, no-output-schema, open-world scraping tool, the description covers discovery logic, return structure, incremental mode, billing, and error reporting. Nothing essential to calling it correctly is missing, and the absence of an output schema is compensated by the explicit row description.

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 schema already documents all 13 parameters and the baseline is 3. The description adds real value on top by explaining the only_new/state_key/min_vote_increase interaction as a coherent workflow and by clarifying the output-row semantics tied to max_requests and max_boards.

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 and resource — find a company's public feature board from a domain and return its top requests — and names the exact fallback discovery strategies (homepage link, then Canny/Featurebase/Frill/UserVoice probes). The output entities (one company_board row plus one request row per request) are spelled out, so an agent knows precisely what it gets.

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 conditional guidance: when the homepage link is used, when platform probing kicks in, and that a probed board is only accepted if it links back to the company domain. It also explains the only_new + state_key incremental mode. It stops short of explicit 'when not to use' or prerequisite framing (e.g. run state_key first), but there are no siblings to route between.

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