History of Market

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuine behavioral context beyond them: the exact outputs (price return, total return, arithmetic mean, CAGR), per-index data availability (sp500 from 1928), and that the current year is partial and flagged `ytd`. The only missing piece is message format/pagination, which is minor for a bounded dataset.

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 tight sentences, front-loaded with the return definition and followed by index availability and the YTD caveat. The index enumeration partially duplicates the schema enum, which is mild redundancy, but each clause carries usable information.

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 specifies the returned fields (price return, total return, mean, CAGR, ytd flag), so the agent can anticipate the response shape. Annotations cover the safety profile. What remains unstated (exact response container, error behavior) is low-impact for a read-only statistics lookup.

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. The description goes beyond the schema's bare enum list by annotating index availability ('sp500 (from 1928)'), which tells the agent something the schema does not about valid year ranges, and clarifies that the range is bounded to 'complete years' for the aggregate statistics.

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: it returns calendar-year price and total returns, plus mean and CAGR, for named indexes. An agent knows exactly what it computes. It does not, however, distinguish itself from siblings like get_latest or get_dataset, which could plausibly return overlapping market data.

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?

No when-to-use guidance, prerequisites, or named alternatives. The only implicit signals are the defaults (sp500) and that the current year is YTD. Nothing tells the agent when this tool is preferable to get_latest or get_dataset.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: a ~60,000 character cap, truncation of long arrays to their most recent rows, the fact that the cut is reported under `windowed`, and that scalars/summary fields are never dropped. That is exactly the kind of context annotations cannot convey.

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, zero filler. The purpose and path examples come first, then filtering semantics, then the truncation caveat — a well front-loaded structure that puts the most decision-relevant facts early.

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 return-value burden and does so reasonably: it describes arrays, scalars, summary fields, and the `windowed` marker. It stops short of describing the overall response envelope or where summary fields live, leaving a small gap for a tool whose output shape matters.

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 baseline is 3, but the description adds meaning beyond it by specifying that `since`/`until` filter on the row's `date` (or `year`) field and that the cap interacts with the `tail` parameter's default behavior. It stops short of documenting formats the schema already 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?

The description gives a specific verb and resource ('Read one published dataset (the JSON behind a chart)') and grounds it with four concrete path examples, so an agent knows exactly what this returns. It never names the sibling that produces those paths (search_charts), so it does not fully differentiate itself from the discovery tools.

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: you supply a dataset path and read it back. There is no explicit statement of when to prefer this over get_latest or annual_returns, and no prerequisite guidance beyond the schema's note that paths come from search_charts.

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 value beyond them by specifying the shape of what comes back (value, unit, observation date) and that data is 'current', which matters because no output schema exists. It stops short of noting staleness windows or rate limits, so not 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?

Front-loaded with the returned payload and its fields, followed by the calling convention. The long enumeration of chart subjects is dense but earns its place since there is no output schema to describe coverage. Slightly list-heavy but no wasted sentences.

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 it does so by naming the returned fields and the set of covered charts. The main remaining gap is routing relative to siblings (annual_returns, get_dataset, search_charts), which an agent would have to infer.

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% and the single `id` parameter is fully documented in the schema with example values. The description's 'pass id for one chart, or omit it for all' merely restates the schema's 'Omit for every reading' clause, adding no new semantics. Baseline 3 applies when the schema does the heavy lifting.

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 a specific verb+resource ('current headline readings') and enumerates exactly which readings are returned (S&P 500 level, Shiller CAPE, forward P/E, VIX, drawdown, breadth, etc.), so an agent knows precisely what this tool produces. It is clearly distinct from siblings like search_charts and get_dataset, which are lookup/discovery tools rather than a latest-readings snapshot.

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?

It explains the two calling modes ('Pass id for one chart, or omit it for all'), which is genuine usage context, but gives no guidance on when to prefer this over siblings such as get_dataset or search_charts, and no exclusions. Usage is implied rather than situated against alternatives.

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 cover the safety profile (read-only, non-destructive, idempotent, closed-world). The description adds behavioral context beyond annotations by disclosing data coverage start dates per index and that results are returned newest first, which helps the agent set expectations for the result set. It still does not describe pagination or rate limits, but the added context is meaningful.

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 compact and front-loaded, starting with the core content returned and following with coverage and ordering constraints. Every phrase contributes useful information without redundancy.

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 rich annotations, complete parameter schema, and absence of an output schema, the description supplies the key return-field summary, index coverage, and ordering. An agent has enough context to call the tool correctly without needing further explanation.

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 all four parameters including defaults and filters. The description only loosely touches on the index parameter by naming sp500 and ndx coverage, adding no syntax or format details beyond what the schema provides; baseline 3 is appropriate.

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 resource (constituent changes) and the fields returned (effective date, company added, company removed, reason), with data coverage for sp500 and ndx and sort order. It lacks explicit differentiation from sibling tools like get_latest or annual_returns, so it is clear but not sibling-aware.

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?

It provides useful context about data coverage windows (sp500 from 2016, ndx from 2020) and ordering (newest first), which implies when the tool is useful. However, it does not state when to use this tool versus alternatives such as get_latest or get_dataset, so usage remains implied rather than explicit.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the return payload (title, question, page, dataset path) despite there being no output schema, which is the key behavioral trait an agent needs for chaining.

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, zero filler. The core purpose and query-matching scope come first, and the return-shape/chaining detail follows immediately. Nothing is repeated from the schema or annotations.

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 simple two-parameter closed-world search with no output schema, the description covers both what goes in (topic/question queries) and what comes back (title, question, page, dataset path) plus the handoff to get_dataset. The only gap is routing guidance relative to the other lookup siblings.

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 baseline is 3. The description goes slightly beyond the schema by giving example query strings ('bear markets', 'Shiller CAPE', 'Nasdaq 100 drawdown', 'monthly seasonality'), which concretely illustrates what shapes of query will match, though it says nothing about the 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 the site's charts') and scopes it to topic or question matching, with concrete example queries. It also names the downstream sibling get_dataset and the exact field (dataset path) that chains into it, so an agent can distinguish this discovery tool from the retrieval siblings without opening any 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?

Usage is implied rather than stated: the mention that results include 'the dataset path to pass to get_dataset' signals this is a first-step discovery tool in front of get_dataset. However, there is no explicit when-to-use/when-not guidance and no comparison against annual_returns, get_latest, or index_changes, so the agent must infer the routing.

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