screen_dividend_stocks

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

No annotations are provided, so the description carries full burden. It discloses that the tool filters by payout size, not yield, which is a key behavioral trait. It also explains the parameter semantics. However, it does not mention authorization needs, rate limits, or potential side effects, which would be useful but not critical for a screening tool.

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 extremely concise: one sentence stating the purpose plus a short clarifying note. Every sentence earns its place, with no superfluous text. The key information is front-loaded.

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 simplicity (2 parameters, output schema present), the description is complete. It explains what the tool does, how to use the parameters, and a critical behavioral caveat. The output schema covers return values, so no further detail needed. No obvious gaps.

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?

The description compensates for the 0% schema coverage by fully explaining both parameters. For min_payout_pct, it gives a concrete example (50 = 50% of par) and context (PSX payouts quoted as % of face value). For limit, it says 'Max results'. This adds significant value beyond the schema's bare types and defaults.

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 that the tool screens the 'upcoming-payouts table' by payout size, with the verb 'screen' and resource clearly identified. It distinguishes from sibling tools like get_upcoming_dividends (which likely lists all) and get_dividend_history (historical), and explicitly notes it's not a true yield screen, avoiding confusion.

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?

The description explains the tool's purpose and includes a note clarifying when not to use it (for true yield) and suggests an alternative (get_quote). However, it does not explicitly compare with closely related siblings like get_upcoming_dividends, leaving some ambiguity about when to prefer this tool over others.

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