SmarterDividends

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world). The description adds value beyond that by disclosing the payload contents — old and new amount, percent change, growth streak, and the pre-change safety score — which is meaningful since no output schema exists. It stops short of stating any auth or rate-limit behavior.

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?

A single dense sentence that front-loads the scope and ends with the default window, so nothing is buried. It is slightly overloaded with enumerations and returned fields, but every clause carries information rather than filler.

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 2-parameter, zero-required read tool with no output schema, the description does the heavy lifting by enumerating the returned fields and stating the default time window. The only gap is sibling routing, which is left to inference.

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 both parameters are already documented, including the full enum for kind and the YYYY-MM-DD pattern for week. The description only restates the default window ('last 7 days'), adding no syntax or semantics the schema lacks; baseline 3 is correct.

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 states a precise verb and resource: every dividend increase, cut, suspension, special dividend, initiation and resumption among U.S.-listed companies going ex in one week. By enumerating all change kinds it implicitly separates itself from the narrower get_dividend_raise_calendar and from get_ex_dividend_calendar, so an agent can route without opening schemas.

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 only implied: 'Defaults to the last 7 days' tells the agent the fallback window, but nothing says when to prefer this tool over get_dividend_raise_calendar (raises only) or get_ex_dividend_calendar (all ex-dates, no change data). No exclusions or alternative-routing guidance is given.

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

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

Annotations already declare a safe, idempotent, closed-world read, so the bar is lower. The description adds real behavioral context beyond them: results are grouped by payer cadence and returned with 'Largest companies first', which tells the agent about ordering before it sets limit.

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?

Three sentences, front-loaded with the resource definition and ending with the useful ordering note. Every sentence carries content; only minor trimming would be possible.

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 3-param read tool with no output schema and full annotation coverage, the description covers scope, categorization, and sort order. It stops short of describing the returned fields or pagination, but nothing essential for correct invocation is missing.

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 67% with month and schedule documented in-schema. The description adds a little interpretation ('including off-cycle schedules' for quarterly, and the trailing-year window for month), but does not explain limit or how the categories interact with the schedule enum beyond what the schema states.

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+resource: 'U.S.-listed stocks that paid a dividend in a given calendar month over the last year,' and enumerates the payer categories. It is clearly distinguishable from calendar-style siblings like get_ex_dividend_calendar, but it never names an alternative to route between them.

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?

'Useful for building a portfolio that pays every month' gives implied usage context, but there is no explicit when-to-use vs when-not, no prerequisites, and no reference to the sibling dividend tools that cover overlapping queries.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value beyond that by specifying ordering ('newest first') and the breadth of the payload, though it does not say what is returned for a non-dividend-paying ticker.

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 resource and its scope, followed by a field list and then clarifying examples. Dense but every clause carries information; the field enumeration is slightly long but earns its place given no output schema.

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 no output schema, the description compensates well by listing the returned fields and their order. The only gap is behavior for tickers with no dividend history and whether the profile returns nulls or errors, which is left unstated.

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 description coverage is 100%, so both parameters are already documented with examples and a 0-100 range. The description restates 'newest first' but adds no syntax or edge-case meaning beyond the schema. Baseline 3 applies.

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 ('get') and resource (one stock/ETF/fund's dividend record) and enumerates the exact fields returned: forward yield, payout ratio, safety grade, ex-dividend dates, fair value, raise/cut history. An agent can distinguish this from the sibling calendar and change-feed tools without opening the schema.

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?

Three concrete example questions ('does Coca-Cola pay a dividend', 'when is O's next ex-dividend date', 'has PepsiCo ever cut its dividend') clearly signal when to reach for this tool. It stops short of naming the sibling it should not be used for when the answer is a bare history delta, so it is not a full 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the five-complete-year lookback window, what "matched" counts, and that a current-year declared/not-declared flag is included. It omits pagination/limit behavior on a tool that returns a list.

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?

Two sentences with no filler, so length is fine, but the first is a dense verb-less noun phrase with an embedded colon list that has to be re-parsed to find the actual action. Front-loading the concept is good; the grammatical shape hurts scanability for an agent.

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 no output schema, the description usefully enumerates the return fields (match count, last and typical raise, declared-yet flag) and the data window, which is what an agent needs to judge relevance. Remaining gaps are the default behavior with no argument and the meaning of limit.

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 67% – month and symbol are documented in-schema, limit is not. The description mainly restates those two ("by month (1-12) or by ticker") and adds only the mild exclusivity hint. It does nothing for the undescribed limit parameter, so it neither compensates for the gap nor adds much beyond the schema.

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 defines the resource precisely: companies whose first dividend raise of the year lands in the same calendar month most years, over the last five complete years, and names the derived values returned (years matched, last/typical raise, declared-yet flag). It never names a sibling, so an agent must still infer how this differs from get_dividend_payers_by_month or get_dividend_changes. Clear purpose, weak differentiation.

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?

"Ask by month (1-12) or by ticker" gives the two entry modes, and the symbol schema says "instead of a month," implying they are alternatives. But there is no when-to-use vs. siblings, and no statement of what happens when neither month nor symbol is supplied even though all three parameters are optional. Usage is implied, not specified.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the default-to-today behavior and the 120-day forward horizon beyond which dividends are unannounced, which affects how results should be interpreted.

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?

A single dense sentence that front-loads the core content (what goes ex, on which date) before the field list and the date-window caveat. Every clause carries information, though the long enumeration makes it slightly heavy to scan.

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 no output schema, the description carries the burden of describing returns and does so explicitly, listing all the fields a caller can expect. Combined with the default and forward-window caveats, an agent has everything needed to call and interpret it.

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 description coverage is 100%, so the schema already documents both date format and the limit bounds; the baseline of 3 applies. The description reinforces the date default and the 120-day horizon but adds no syntax or constraint detail beyond the schema.

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?

Names a specific resource (every U.S.-listed dividend going ex) scoped to one date, and enumerates the returned fields (amount, pay date, yield, safety grade, change, last day to buy). This is clearly separable from siblings like get_dividend_raise_calendar or get_dividend_payers_by_month without opening a schema.

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 implies usage via 'Defaults to today; dates up to 120 days ahead include announced dividends', which tells the agent the useful date window. However, it never says when to pick this tool over the sibling dividend tools, so the routing guidance is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context about which metrics come back, but says nothing about result ordering, the 100-item cap, or the default limit of 25, which matter for a list 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?

A single dense but well-structured sentence that front-loads the resource and then the returned metrics; there is no filler. It is long, but almost every clause carries information the agent needs to judge relevance.

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 four optional params, no output schema, and modest annotation coverage, the description does well on the returned metrics but leaves the list behavior underspecified — default page size, sort direction, and whether the results are a ranked table or per-fund objects are all unstated.

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 50%: family and symbol carry descriptions, while sort and limit are undocumented in the schema. The description partially compensates by listing 'annualized distribution rate', 'trailing 12-month yield' and 'one-year total return', which give the agent a hint at what sort=distribution_rate and sort=total_return mean, but it never connects them to the parameters explicitly.

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 the concrete resource (option-income/covered-call ETF distributions) and enumerates the specific data fields it returns (latest payout, next payout, frequency, distribution rate, TTM yield, 1-year total return), with representative issuers and tickers. It is clearly distinguishable from the sibling dividend tools, though it never uses an explicit verb like 'list' or 'returns'.

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 scope implies when it applies (option-income/covered-call ETFs rather than ordinary dividend payers), but it never states when to prefer this over get_dividend_profile or get_dividend_changes, and gives no exclusions or prerequisites. Usage is inferable from the domain vocabulary rather than stated.

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

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

Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is covered. The description adds genuinely non-structured behavior: result ordering is biased toward dividend payers and larger companies, which affects how an agent should interpret/rank hits. It doesn't mention result count limits or empty-result behavior, keeping it from a 5.

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?

Three short sentences, front-loaded with what it searches, then ordering behavior, then the concrete use case with examples. No filler, and the examples make the expected query style concrete.

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?

No output schema exists, and the description sufficiently implies the return value (a ticker lookup) plus ordering semantics. The only real gap is the unexplained 'limit' parameter and the maximum result cardinality, which an agent would need to know to size a search.

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 50% – 'query' is documented in the schema and the description largely restates it with examples, while 'limit' (default 10, max 25) is never mentioned in either. The description adds example query forms but does not compensate for the undocumented limit parameter.

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 ('Search U.S.-listed stocks, ETFs and funds') and bounds the searchable surface (company/fund name or ticker). This is clearly distinct from the sibling tools, which are all dividend/income oriented, and an agent can tell the difference without opening the schema.

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 an explicit downstream use case ('turn a name ... into a ticker for get_dividend_profile'), naming the sibling it feeds. It stops short of saying when *not* to use it, but the intended entry-point role is unambiguous.

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