Timefire

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

The annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description does not need to restate that. It adds real value beyond them by disclosing the error behavior for ungraded dates and out-of-book tickers, plus what evidence is returned. It stops short of describing response shape in detail, but an output schema exists for that.

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 purpose and followed by the usage routing and error rule. Dense but every clause earns its place; the first sentence is long and comma-heavy, which slightly reduces scannability.

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 two-parameter read tool with full schema coverage and an output schema, the description supplies what structured fields cannot: when to prefer the sibling, what evidence comes back, and what counts as an error. Little is missing 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 coverage is 100%, and the schema already explains the ticker's case-insensitivity and the YYYY-MM-DD date format with a pointer to list_resolved_batches. The description adds only the failure semantics for these two inputs, so the baseline of 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 states a specific verb and resource ('Get the stored evidence behind one stock's forecast in a graded book') and immediately enumerates what that evidence includes: rank, side, regime, lookback returns, news and notes. It also explicitly distinguishes itself from the sibling get_stock_resolved_history, so an agent can choose between them without opening either 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?

It gives explicit when-to-use guidance ('Use this to see the context a stock was ranked in') and names the alternative and its condition ('get_stock_resolved_history to find which books hold it'). It also states the failure conditions — an ungraded date or a ticker absent from the book is an error — which is exactly the guidance needed to avoid a bad call.

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, non-destructive, closed-world), and the description adds genuine behavior: the default weighting, the error on ungraded/unknown dates, and the data-model caveat that per-prediction cap_weight must not be assumed to match either book without checking inference_metadata.weighting. That caveat is partly about a neighboring data model rather than this call's own behavior, and the enumerated return fields partly duplicate the output schema, keeping it just short of 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 purpose and default in the first clause, then alternatives, then the error case; dense but organized. A sentence is partly spent on per-prediction field naming that belongs to a different tool's surface, which is slight scope creep in an otherwise tight definition.

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 an output schema present, the description need not enumerate return values, and both parameters are covered by schema descriptions plus default/pairing context. It supplies the alternative tool, the default, the failure mode, and the benchmark pairing, so nothing an agent needs to call it correctly 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 100%, so the baseline is 3, but the description adds meaning beyond the schema: it says "cap" is not merely the default but the portfolio the ledger's verdict grades, and states the invariant that each weighting always pairs with a specific benchmark. That drives the choice of parameter value, which the schema alone does not.

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 ("Get a resolved book's portfolio") and immediately disambiguates the two modes it returns (market-cap-weighted vs SPY, equal-weighted vs RSP). It also names the sibling it is not (get_simulation_nav), so an agent can separate it from adjacent tools without opening either 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?

Explicitly routes usage: "Use this for one book's result, and get_simulation_nav for the running portfolio across books," and adds the failure condition "An ungraded or unknown date is an error." It also documents the default mode and the pairing invariant (equal↔RSP, cap↔SPY), leaving little 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds real behavioral scope — that results span "every graded book" and that hit rates apply only to "books graded under the published rule" — which tells the agent the metric population is filtered, not universal. It says nothing about cost, latency, or empty-result behavior, so it stays at a solid 3 rather than earning more.

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, front-loaded with the core computation before the sibling routing. The first sentence is dense and jargon-heavy ("decile", "rank bucket", "graded book") but every clause names a distinct output, so nothing is padding. Slightly tighter phrasing of the metric list would push this to a 5.

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 parameters, an output schema carrying the return values, and annotations carrying the safety profile, the description only needs to convey analytical scope and sibling routing — both of which it does. The one assumed term, "published rule", is resolvable via the sibling get_universe_and_scoring_spec, which is a reasonable division of labor rather than a gap.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly does not waste space restating an empty 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?

States a specific verb ("Check whether forecasts matched outcomes") and then enumerates exactly what is computed: mean predicted vs mean realized return by decile across every graded book, plus hit rates by rank bucket and by side. This is concrete enough that an agent can distinguish it from return-summary 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?

Explicitly says when to use it ("Use this to judge how well the ranking held up") and names the alternative with its own purpose ("get_track_record_stats for headline returns and the verdict tally"). The routing decision between the two tools is fully determined by the description.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description does add real behavioral context beyond that — the book is only 'served once its long picks are fully graded, so other rows can still have null outcomes' — which warns the agent about partial null data. However, it stops short of describing pagination, size/volume expectations, or anything about the response shape, so it sits at adequate rather than rich.

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 core definition followed by the grading caveat and sibling routing — no filler. Slightly dense in places ('verify_batch for the book's proof'), but every sentence carries information the agent needs.

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 single-parameter read tool with full schema coverage, annotations, and an output schema, the description covers purpose, discovery path, grading precondition, null-outcome caveat, and error condition. Nothing an agent needs in order to call it correctly 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 description coverage is 100% and the single parameter already documents the YYYY-MM-DD format plus the pointer to list_resolved_batches. The description adds no format, range, or edge-case detail beyond the schema, so 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 and resource ('Get one graded book with every forecast and its outcome') and immediately defines the domain term 'book' as 'one trading day's full S&P 500 slate.' This is clearly distinct from siblings like list_resolved_batches and get_stock_resolved_history, which return lists or per-stock histories rather than a single day's full slate.

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?

Explicitly routes the agent to the right siblings: list_resolved_batches to discover the date, verify_batch for proof, get_book_portfolio for portfolio data. It also names the failure condition ('An ungraded or unknown date is an error'), which tells the agent when not to call with an arbitrary date.

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=true and destructiveHint=false, so safety is covered; the description adds the non-obvious disclosure that the series is truncated at the newest date where every book is revealed, because later values would include sealed positions. That is exactly the kind of caveat an agent cannot infer from structured fields, though the "books still sealed" phrasing is somewhat opaque and no limits or pagination behavior are mentioned.

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?

Four sentences, front-loaded with the resource and its modes, then the row shape, then the truncation constraint, then the sibling routing. No filler or repetition; every sentence contributes 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 an output schema present and rich annotations, the description needs only to supply the semantics structured fields cannot: row granularity, benchmark pairing, and the series-truncation rule. Those are all present, plus a pointer to the complementary trades tool, leaving nothing an agent needs in order to call this correctly.

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%, and the description's weighting explanation ("cap" vs SPY default, "equal" vs RSP) largely restates the schema's own weighting description. It adds the useful row-level fact that both benchmarks appear on every row, but nothing about date-range semantics beyond what the schema documents. 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?

States a specific verb and resource ("Get the paper portfolio's daily value (NAV)") and immediately qualifies it with the two weighting modes and their benchmarks, so the agent knows exactly what series is returned. It is clearly distinguishable from get_simulation_trades, which is named as the trade-level counterpart.

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?

Explicitly routes the agent: "Use this for portfolio value over time, and get_simulation_trades for the trades behind it." That gives a clear use case plus a named alternative. It does not differentiate against get_book_portfolio, which also concerns portfolio value, so no exclusion is stated for that sibling.

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 establish a safe read of a closed world, so the marginal bar is lower, and the description clears it by disclosing ordering (newest first), that open positions never appear, and that date bounds bind on the open day rather than the close day. The non-obvious explanation that cap and equal weightings trade at identical prices but differ in size and P&L is real behavioral context an agent could not infer from the schema.

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, front-loaded with the resource and ordering before the weighting variants and the sibling redirect. The stacked parentheticals on weighting are dense and slow a first read, but essentially every clause carries information an agent needs.

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 four-parameter read tool with full schema coverage, annotations, and an output schema, the description covers the remaining ambiguity: what is excluded (open positions), ordering, truncation without paging, and date-bound semantics. Nothing needed to invoke it correctly 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 100%, so a 3 is the baseline, but the description goes beyond it: it explains what the weighting choice actually changes (size and P&L despite identical prices) and clarifies that dates filter on the opening day, which the schema's "earliest date to include" does not say. The limit/no-paging behavior is reinforced with the workaround of narrowing dates.

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?

"Get the paper portfolio's closed trades from resolved books, newest first" names a specific verb, resource, source scope, and ordering. It explicitly separates itself from get_simulation_nav (portfolio value) and implicitly from position-oriented siblings by stating open positions never appear.

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 states the use case (individual trades) and names the alternative with its distinct purpose (get_simulation_nav for portfolio value), plus a concrete remedy for truncation: narrow the date bounds. The exclusion of open positions is stated outright rather than 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 establish a safe read (readOnlyHint true, destructive false, closed-world), and the description adds real behavioral context beyond them: results are restricted to graded books, ordered newest first, and an unknown ticker yields an empty list rather than an error. It stops short of explaining truncation behavior when the 120-row default limit is hit, which is the one remaining ambiguity.

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 that are front-loaded with scope and ordering, then usage routing, then the edge case. Every clause carries information; nothing is repeated from the title or 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?

An output schema exists so return values needn't be specified, yet the description still summarizes the returned columns, and it covers filtering, ordering, alternatives, and the empty-result case. Nothing an agent needs to call this correctly 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 100%, so the baseline is 3; the description earns an extra point by documenting the ticker edge case (unknown ticker returns an empty list), which the schema does not state. The limit parameter's truncation semantics remain schema-only, but nothing is left undocumented overall.

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 (get one stock's rows) plus scope (graded books only, newest first) and enumerates the returned fields (forecast, rank, pick side, outcome per book). It is immediately distinguishable from get_resolved_batch (whole book) and explain_resolved_prediction (single row evidence).

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 routing: 'Use this to follow one ticker across books', then names both alternatives with the condition that selects each — explain_resolved_prediction for per-row evidence, get_resolved_batch for a whole book. No inference required.

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, closed-world, non-destructive), so the description's added value is data-scope semantics: it discloses that aggregates come only from fully resolved books, that grading is cap-weighted on long picks, and that the 69 pre-published_rule_from backtest books follow a different rule and are segregated into backtest_ fields. That is genuinely useful context an agent cannot infer from annotations. It stops just short of 5 because the rule-versioning sentence is dense and partly re-describes output fields.

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 'what it does' statement, which is good, but the middle sentence strings together hit-rate rule scope, the 69-book cohort, and the backtest_ field names in one hard-to-parse clause. Some of that field-level detail is redundant given an output schema exists.

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 zero-parameter aggregate tool with annotations and an output schema, the description covers data inclusion criteria, grading methodology, rule versions, and sibling routing. The remaining gap is minor: no indication of the time horizon or coverage of the aggregates beyond 'fully resolved books'.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. No misleading parameter claims are made.

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 (get aggregates over fully resolved books) and enumerates the aggregate families: forecast counts, returns, hit rates, and beat/flat/trail SPY verdicts. It also distinguishes scope from siblings, calling out get_calibration and get_book_portfolio by name.

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?

Explicitly routes the agent: 'Use this for overall performance, get_calibration to test the ranking itself, and get_book_portfolio for a single book.' The alternative-selection condition is stated directly rather than implied.

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?

The annotations already declare this as a safe, read-only, closed-world operation, so the description does not need to restate safety. It adds useful scope context by saying the scoring rules are versioned and tied to the latest graded book, but it does not add behavioral details such as freshness, caching, or result ordering.

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 two tight sentences with no wasted wording. It front-loads what is returned and then immediately gives the interpretive use case.

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 no-parameter, read-only tool with an output schema, the description supplies enough context: it identifies the returned artifacts and explains when to call it. The output schema covers return structure, and annotations cover safety, so no critical detail 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?

This tool takes no parameters, so there are no parameter meanings for the description to supplement. The baseline score of 4 applies because the empty schema and 100% schema description coverage leave nothing ambiguous on the input side.

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 specific verb and a concrete set of resources: versioned scoring rules, metric definitions, and the latest graded book's stock universe. It is clear what the tool returns, though it does not explicitly name or differentiate itself from sibling 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?

It gives a clear usage condition: use this before interpreting a stat or verdict to learn how books are graded and which stocks are covered. It does not provide when-not-to-use guidance or name an alternative sibling, so it stops short of a full routing rule.

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=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds behavior the annotations cannot: results are newest-first, exactly one summary row per book, and ungraded date ranges yield an empty list rather than an error — useful for an agent interpreting results. It stops short of describing the default 60-row cap or any pagination semantics.

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 output shape, then the domain definition, then the routing advice. No sentence repeats the name or title, and the terminal empty-list note is a single useful clause.

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 an output schema present, return values need not be spelled out, yet the description still summarizes the row contents and ordering, and covers the empty-result edge case plus next-step tools. The only minor gap is that it doesn't flag the default limit of 60 or what happens when more books exist than the cap allows, leaving that entirely to the schema.

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%, with limit, from_date and to_date each documented inline including format (YYYY-MM-DD) and bounds. The description mentions only 'trading_date' and 'date' generically and adds no syntax or filtering nuance beyond the schema, so the 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?

The description opens with a specific verb and resource ('List graded books') and then defines the domain term explicitly ('A book (or batch) is one trading day's full S&P 500 slate'). It also enumerates the summary row fields (date, returns, alpha against SPY and RSP, verdict), making it distinguishable from get_resolved_batch, which handles a single book.

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 gives an explicit workflow: use this tool to find a trading_date, then call get_resolved_batch for every forecast or verify_batch for the proof. That names the alternatives and the condition that selects each, so an agent knows exactly where this tool sits in the chain.

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 establish the safe read-only, closed-world, non-destructive profile, so the bar is lower. The description still earns credit for disclosing the empty-result edge case ("No match returns an empty list, so try other words") and the shape of each hit, which tells the agent not to treat zero results as an error.

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?

Four short sentences, front-loaded with purpose, then returns, then routing, then the failure mode. Every sentence carries information, though the hit-contents sentence overlaps with what the output schema already provides.

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 two-parameter read-only search with full schema coverage, rich annotations, and an output schema, nothing an agent needs is missing: purpose, routing rule, and the empty-result behavior are all present. The only unstated detail, ranking behavior, is not needed to call it correctly.

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%, with both query (max 8 words, 200 characters) and limit (1–20, default 5) fully documented inline. The description's "a few words" hints at the query's nature but adds no syntax, formatting, or limit semantics beyond the schema, so the baseline of 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?

The description uses a specific verb ("Find") applied to a named resource ("developer guides and site pages") and states the match mode ("a few words"). It then draws a sharp line against the data-oriented siblings: "not for record data." An agent can distinguish this from get_track_record_stats or get_resolved_batch 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?

It gives explicit when-to-use ("how Timefire works and what its terms mean") and when-not ("not for record data") guidance, which is the key routing decision for this toolset. It stops short of naming a specific sibling to use instead for record data, leaving the agent to pick among the many data tools.

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=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real context beyond them: it explains that the 'verified' field is the server's own check while the evidence exists so the caller can repeat the verification independently, and it discloses the error behavior for ungraded dates. It stops short of describing latency or payload size, which keeps it at 4 rather than 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 sentences, each earning its place: what is returned, how to interpret the verified field, and when to use this versus the sibling plus the error case. The most important scoping information is front-loaded and there is no repeated or filler text.

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?

An output schema exists, so return values need not be restated, and the description still summarizes the payload shape and the meaning of the 'verified' field. Combined with the sibling routing and the ungraded-date error case, an agent has everything needed to invoke this correctly for a one-parameter tool.

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% and the trading_date parameter is well documented with its YYYY-MM-DD format and a pointer to list_resolved_batches. The description adds meaning the schema does not: that an ungraded or unknown date is treated as an error, which tells the agent how to interpret a bad value. Baseline plus added error semantics justifies a 4.

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 (public proof for one graded book), then enumerates exactly what is returned: signed payload, hash, signature, content address, timestamp material, and verification steps. It also explicitly distinguishes itself from the sibling get_resolved_batch, so an agent can tell them apart without opening either 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 explicit when-to-use guidance ('use this to check a book's signature and timestamp') and names the alternative with its purpose ('get_resolved_batch to read its forecasts and outcomes'). It also states a failure condition — an ungraded or unknown date is an error — which is the exclusion an agent most needs.

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