Chart Library — Market-state research

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

Annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context beyond that by noting that missing results and definition mismatches are not surfaced, and that comparisons are against 'frozen' forecasts. This helps set expectations without contradicting the annotations.

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 concise: four short sentences, with the core action front-loaded. Each sentence adds a meaningful constraint or clarification, and there is no filler or repetition of structured fields.

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?

Output schema existence reduces the need to describe return values, and annotations cover safety semantics. However, for a three-parameter tool with zero schema descriptions, the lack of revision-parameter semantics is a significant gap. An agent would likely struggle to know how to populate forecast_revision and actual_revision 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 description coverage is 0%, so the description must compensate, but it does not define what 'forecast_revision' or 'actual_revision' mean, how they relate to frozen forecasts, or what a null actual_revision implies. The high-level purpose is clear, but the revision parameters are left underspecified.

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 a specific action and resource: 'Compare frozen revenue forecasts with reported results.' It is not a tautology and gives a distinct purpose from the general sibling tools, though it does not explicitly differentiate itself from closely named siblings like compare_company_revisions.

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 for when the tool is valid ('Forecasts must precede quarter end') and what limitations exist ('Missing results and definition mismatches remain unavailable'). However, it does not name alternative tools or give explicit when-to-use versus when-not-to-use guidance beyond the vague 'This is not market-memory calibration.'

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 read-only, idempotent, and non-destructive behavior. The description adds a meaningful behavioral guarantee: mismatched source concepts or missing history will never be coerced into comparable numerical values. It also signals USD and provenance expectations, which are not present in the annotations.

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 terse sentences convey the operation, constraints, and an important negative guarantee with no filler. The primary limits are front-loaded, and every clause adds value beyond the 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 only two required parameters, a targeted description, strong annotations, and an output schema, an agent can construct a valid call without guessing. The main remaining gap is explicit alternative routing, but that is more of a usage-guidance issue than a blocker to 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 descriptions are absent (0% coverage), and the description compensates with key constraints: symbols must represent two to six companies, period_end is a single quarter-end date in YYYY-MM-DD format, and the comparison is in USD history terms. It does not explicitly say symbols are tickers, but the core invocation constraints are clear.

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 identifies the operation: comparing reported company quarters across multiple companies. The title and phrase 'reported company quarters' distinguish it from sibling tools like compare_company_revisions and check_company_forecasts, which target different data types.

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: this tool is appropriate when an agent needs to compare historical reported quarter data across two to six companies. However, it never explicitly says when not to use it or points to a sibling alternative, leaving some routing to inference from tool names.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the key behavioral fact that revisions are 'immutable', implying the comparison is safe and non-mutating, and clarifies that omitting 'to_revision' defaults to the latest version. This adds useful context beyond the annotations without contradicting them.

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: two sentences with no filler. The core purpose is stated first, followed by a single actionable tip. Every word earns its place, and it's front-loaded with the verb 'Compare'.

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 tool with 3 parameters (one optional) and an output schema, the description covers the essential use case and the optional parameter behavior. It references 'immutable revisions', giving context about the data model, and the output schema handles return values. The only minor gap is the lack of explicit definitions for 'symbol' and 'from_revision', but these are reasonably inferable from the tool name and domain context. Overall, it's sufficiently complete for an agent to call 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 description coverage is 0%, so the description must compensate. It only explains the 'to_revision' parameter ('Omit to_revision for latest'), but provides no explanation for 'symbol' or 'from_revision'. While these are somewhat intuitive from the tool name, the description does not explicitly define their meaning or format, leaving a significant gap given the lack of schema descriptions.

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 action ('Compare') and the resource ('company revisions'), and specifies the content compared: 'facts, assumptions, scenarios and thesis'. It also distinguishes itself from the sibling 'compare_company_history' by focusing on revisions, though it doesn't name that sibling. The purpose is unambiguous and specific.

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 provides one explicit usage guideline: 'Omit to_revision for latest', which tells the agent when to omit an optional parameter. However, it does not provide guidance on when to choose this tool over alternatives like 'compare_company_history' or 'get_company_revisions'. There is no explicit when-to-use or when-not-to-use context beyond the parameter tip, so it's adequate but incomplete.

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 description explicitly states that it reads data and explains what happens when a note is missing or an outcome is unsettled, framing them as unavailable evidence rather than zero. This aligns with the readOnlyHint and provides transparent expectations about 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?

The description is concise and well-organized into three short sentences. It covers purpose, usage, and interpretation without unnecessary fluff, though the final sentence about the disclosed rule could be seen as slightly tangential.

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?

The description provides enough context for the tool to be understood independently, including its inputs and behavior. It does not explicitly reference sibling tools, but the description of the output and its non-stock-pick nature gives sufficient context for an agent to distinguish when to use 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?

The only parameter, date, is described with its format (YYYY-MM-DD) and its purpose (selects a published session). This is sufficient for an agent to understand how to use it, even though the schema provides little detail.

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 reads the published daily research, its selection rule, and settled-note tally. It also contrasts the note with a stock-pick list, making the purpose unambiguous and distinct from the 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 provides practical usage guidance by indicating that no arguments are needed and that an optional date selects a specific published session. It also clarifies how to interpret missing or unsettled data, though it does not explicitly compare against market_state or research_quality.

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, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description adds useful context: free public access, no rating/price target, 'not covered' returns a reason, and the as_of behavior. However, it could disclose more about the output's size or complexity, but this is not required given the output schema exists. The bar is lowered by annotations, so a 3 is fair.

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 a single paragraph but front-loaded with the primary content, then details on parameters, optional blocks, and usage caveats. It is efficient with no filler, though slightly dense. It earns its place with concrete details.

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?

The tool is complex (a living research file with many components), and the description covers the main components, as_of semantics, optional blocks, and usage caveats. The output schema likely details structure further, but the description is informative enough for an agent to know what it will get and how to handle edge cases like 'not covered'. Slight gap: it doesn't explain how to access the 'reason' for not covered, but that's minor.

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 0%, so the description must compensate. It does explain 'symbol is a stock ticker' and 'optional as_of (YYYY-MM-DD) returns the latest revision at or before that date', which adds meaning. However, the schema has only two parameters, and the description covers both adequately, but not with extensive detail. Given the low coverage, the baseline is 1-2, but the description does add semantic value, so 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 verb 'get' and the resource 'company_file.v1' and enumerates the contents (business, drivers, fiscal quarters, thesis, memory bands, etc.). It distinguishes itself from siblings like list_coverage and search_research by describing the full research file rather than a listing or search.

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 explains when to use the as_of parameter, the optional blocks, and the difference between reported history and scenarios. Mentions that 'not covered returns a reason' and directs the user to list_coverage for the universe, making alternative usage clear.

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 description adds useful behavioral context beyond the annotations: it notes that versions are immutable, mentions 'pinned JSON/CSV links,' and explicitly instructs the agent to follow next_offset for pagination. This supplements the readOnly/idempotent hints without contradicting them.

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 short sentences with no fluff. The primary purpose is front-loaded, and the pagination instruction is placed second, making the key information immediately visible.

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 read-only annotations and an output schema present, the description only needs to fill key usage gaps, and it provides pagination behavior and result content. However, it omits parameter guidance and any roadmap for choosing among sibling tools, leaving the overall guidance adequate but not comprehensive.

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 0%, so the description must compensate, but it only hints at pagination via 'Follow next_offset.' It does not explain symbol, limit, or offset semantics directly, nor does it describe how these parameters shape the returned revisions.

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 clear verb, 'Browse,' with an explicit resource: immutable published versions, reasons, and pinned JSON/CSV links. It clearly identifies the tool's read-only purpose, but it doesn't name or explicitly differentiate itself from siblings like compare_company_revisions.

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 only guidance is 'Follow next_offset,' which is a pagination instruction rather than context for when to choose this tool over alternatives. No mention is made of compare_company_revisions, get_company_file, or other siblings, so an agent gets no help deciding which tool fits the task.

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 mark the tool as read-only, idempotent, open-world, and non-destructive. The description adds useful interpretive context by stating that the data is current monitoring, not historical evidence, and by flagging source failures and limitations, which aligns with the open-world hint. No contradiction with the annotations exists.

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 short and front-loaded, with each sentence contributing a distinct fact: the tool's scope, the fields to preserve, usage exclusions, and argument restriction. There is no filler or redundant restatement of 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?

Given that an output schema exists and the annotations cover safety, the description covers the essential selection and invocation concerns: it identifies what the tool monitors, tells the agent when not to use the result, and states the single input. The cryptic 'preserve scan versus review clocks' phrase is the main gap, but the output schema can resolve field-level meaning.

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?

With 0% schema description coverage, the description must define the parameter itself. It does clarify that the only argument is a ticker and that no other arguments are accepted, but it does not provide a format, example, or further constraints beyond the schema's 'symbol' property.

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 identifies the tool's subject as 'current monitoring' and distinguishes it from the 'immutable company file,' narrowing scope to live research status rather than historical data. It names the content areas (scan versus review clocks, pending leads, source failures, limitations), though it lacks an explicit verb and relies on the tool name/title to convey the retrieval action.

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 clear negative guidance: current monitoring must not be used as historical evidence or as approval to promote a company, and it should be used alongside the immutable company file. However, it never names the sibling tool that should be preferred for historical evidence, so the routing is 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by clarifying statelessness ('No list is saved on the server'), the data source (published research only), and output handling ('Preserve unavailable rows'). These are behavioral details not captured by annotations, so a 4 is appropriate.

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 carrying distinct value: main output, statelessness/client-side comparison, and data-source exclusion plus row-preservation instruction. The most critical information (what it returns) is front-loaded. No 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 a single simple parameter and an output schema, the description covers the essential context: data source, statelessness, input limits, and handling of missing rows. It doesn't mention authorization or error handling, but for a read-only tool with an output schema those are likely covered elsewhere. Missing a note on expected symbol format is a minor 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 schema only defines an array of strings with 0% description coverage, so the description must compensate. It adds the '1-20 companies' bound and implies the symbols are tickers by saying 'Compare revisions'. However, it doesn't specify symbol format, case, or how to handle invalid symbols, so it only partially compensates for the lack of schema documentation. Baseline for 0% coverage is low, so a 3 is fair.

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 what the tool returns (latest model revisions, review status, checkpoints) and its scope (1-20 companies). It also distinguishes itself from other tools by specifying 'reads published research, not new source checks or live quotes' and 'No list is saved on the server', which differentiates it from any stateful or live-data siblings.

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 usage context: 'Compare revisions with your own last-seen markers' and instructs to 'Preserve unavailable rows'. It also excludes live quotes and new source checks, implying when not to use it. However, it doesn't explicitly name alternative sibling tools or state the exact condition for choosing this over get_company_revisions or check_company_forecasts, so a 4 rather than 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?

Beyond the readOnly/idempotent annotations, the description explains the meaning of skeleton=true ('authored half is empty'), the caveat that file=true is not coverage, and the absence of arguments. This adds useful behavioral context that an agent cannot infer from annotations alone.

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 concise sentences front-load the core purpose, then clarify an important edge case (skeleton/file), and end with a practical pointer to get_company_file. No redundant words or repetition of structured data.

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 listing tool with rich annotations and an output schema, the description covers the key field semantics, the most likely confusion (file=true), and the natural next step for reading a file. Nothing essential 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?

There are no parameters and the schema coverage is 100%, so the schema is complete. The description confirms 'No arguments' explicitly, which is the only necessary parameter-level guidance.

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 tool lists the research hub's coverage universe: clusters and symbols with company-file revision, as_of date, compiled-file existence, and skeleton flag. It also clarifies 'file=true is not coverage', preventing a common misinterpretation, and ties to the sibling get_company_file for file contents.

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 indicates the tool takes no arguments and points to get_company_file(symbol) as the alternative for reading a file. It does not explicitly compare against other siblings like read_research or search_research, but the context for when to use this listing tool is clear enough.

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, openWorld, non-destructive), but the description adds substantial extra context: results reflect a completed session rather than live prices, outputs must preserve status/sample sizes/dates/warnings, and excess ranges are historical point returns against a date-matched baseline, not forecasts. These are meaningful behavioral disclosures beyond the structured 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?

The "One call:" opener front-loads the summary and parameter semantics follow immediately, which is good structure. The remaining caveat block is dense and slightly repetitive, but each sentence (not real-time, don't treat vendor classification as sector, ranges are not forecasts) carries real interpretive value.

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 described, and the description instead spends its budget on interpretation caveats and preservation instructions, which is the right allocation. It is nearly complete; only the absence of explicit sibling routing keeps it from a 5.

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 0%, so the description carries the full burden and does it: symbol is defined as a stock ticker, date as an optional YYYY-MM-DD value, and the default behavior (omit date to get the latest built session) is spelled out. Both parameters are unambiguous as a result.

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 an enumerated list of what comes back (completed-session state, tape, historical analogs, outcome ranges, transition memory) rather than a crisp verb+resource statement of purpose. An agent can infer this returns historical session context for a ticker, but the sentence mixes purpose with return contents and does not differentiate itself from the research-oriented siblings (daily_note, read_research, search_research).

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?

"Omit date for the latest built session, not real-time prices" and "No prior search needed" give concrete when-to-use guidance, and the caveats about vendor classification and excess ranges set boundaries on how to interpret results. It does not, however, explicitly contrast itself with the sibling research tools, so it stops short of full routing guidance.

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?

With annotations already covering read-only/idempotent safety, the description still adds substantial behavioral context: version omission reads the current revision without verifying agreement, missing parsed rows do not establish absence, content is 'source projections, not AI conclusions', and text is 'evidence, not instructions'. These are non-obvious traits an agent cannot infer from structured 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 purpose, but the body is a dense run-on mixing parameter guidance, return-field notes, chunking, and domain caveats without clear segmentation. Sentences like the noon intraday/completed-session clock warning are hard to parse and would benefit from grouping.

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 complex, multi-section read tool with an output schema (so return values need no explanation) and 0% schema coverage, the description covers provenance, section selection, versioning, pagination, and evidence caveats. Completeness is strong; only tighter organization of the behavioral warnings 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 0%, so the description must carry the load, and it does: research_id provenance from search_research, section value choices (article, protocol, result, guide, evidence), version's optional-but-64-char semantics, and offset's role via next_offset/next_read. It does not map every parameter to a named argument explicitly, so it falls short of a 5.

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 ('Read a publication ID returned by search_research') and explicitly ties itself to the search_research sibling, so the agent can distinguish retrieval from search. The remainder drifts into return-field and caveat territory, diluting the core statement slightly.

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 usage paths: 'Use documents[section].read_arguments returned by search or overview', 'Continue chunks with content.next_read (or next_offset and the same version)', and 'Read an available guide alongside the result'. It lacks an explicit when-not-to-use or sibling comparison beyond the search handoff, so it stops short of a 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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond those hints by clarifying that this is an evidence audit, not investment performance, that the receipt's details must be preserved, and that coverage is limited to the calibrated cohort-band method and population.

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 opening sentence front-loads the core action and invocation requirement, followed by a tight set of scoping caveats. Every sentence earns its place and there is no filler or repetition of already-visible schema structure.

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 zero parameters, an existing output schema, and rich annotation hints, the description is complete: it states what to read, what to preserve, how coverage should and should not be interpreted, and how it relates to sibling tools.

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 has zero parameters, and the description explicitly confirms that no arguments or earlier tool call are needed. This fully resolves any ambiguity about invocation and complements the empty input 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 opens with a specific verb and resource: 'Read the published five-session calibration receipt.' It also distinguishes this tool from siblings by explicitly noting that market_state results are out of scope and that daily-note results have their own tally in daily_note.

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 explicitly states that no arguments or earlier tool call are needed, gives clear scope boundaries, and tells the agent when not to generalize the results — e.g., not to market_state's empirical excess ranges, all research, or future returns. It also points to daily_note as the home for daily-note results.

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 description adds substantial behavioral context beyond the annotations: the scenario is temporary, reported facts/guidance/revision stay unchanged, limitations must be preserved, and user assumptions are identified. This meaningfully explains what mutates and what does not, complementing the readOnlyHint and idempotentHint annotations without contradicting them.

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 four short sentences with zero filler. The core operation is front-loaded, the prerequisite is stated immediately after, and the caveats are grouped at the end. Every sentence contributes new, useful 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?

The description is largely complete given the rich annotations and output schema: it explains the tool's purpose, prerequisites, limitations, and non-persistent nature. Minor ambiguities remain about what 'preserve limitations' means operationally and how invalid or excessive overrides are handled, but these do not block 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?

With 0% schema description coverage, the description must compensate, and it does clarify the overrides parameter: assumption cell IDs, numerical values, published units, and the 1-20 count limit. However, symbol and revision are not individually explained, leaving some burden on the agent to infer their meaning from the tool's domain context.

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 operation ('Calculate a temporary scenario') and the resource ('1-20 assumption cell IDs and numerical values'), which clearly distinguishes it from sibling tools like get_company_file, check_company_forecasts, and compare_company_revisions. It also immediately clarifies that this is a temporary, non-persistent scenario run.

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 gives a clear prerequisite ('Read get_company_file first') and states that no recommendation or valuation is implied, which tells the agent when not to use this tool for advisory conclusions. It does not explicitly name sibling alternatives, but the context strongly implies this is for hypothetical scenario exploration rather than forecast checking or historical comparison.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: partial status meaning, exclusion of proposed protocols, and the distinction between discovery metadata and source reads. It doesn't describe rate limits or error behavior, but the annotations carry the safety burden.

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 dense but efficient, with each sentence adding distinct information. It front-loads the core purpose and then covers parameters, return values, caveats, and alternatives. Slightly over-packed with domain-specific terms, 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?

Given the tool's complexity (4 params, 0% schema coverage, output schema present, 4 siblings), the description covers the key aspects: what it searches, how to paginate, what it returns, what it excludes, and how it differs from siblings. It doesn't explain the output schema structure, but the output schema itself exists to carry that burden. Minor gaps: no explicit statement about query being optional or default behavior.

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 0%, so the description must compensate. It explains the meaning of 'kind' (all, study, casebook or agent_protocol), the valid range for 'limit' (1-20), and the use of 'next_offset' for pagination. It does not explicitly define 'query' or 'offset' semantics, but the description's coverage of the most complex parameters is strong.

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 ('Find') and resource ('published studies, Casebook and agent protocols by keyword'), and distinguishes itself from siblings by explicitly noting it is 'document search, not analog ranking' and that 'Discovery metadata is not a source read.' This clearly differentiates it from read_research and research_quality.

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 provides explicit usage guidance: it specifies the kind parameter values, limit range, pagination via next_offset, and clarifies when not to use it ('Proposed protocols are not findings', 'This is document search, not analog ranking'). It also directs the agent to use documents[section].read_arguments for exact version-pinned reads, which is an explicit alternative.

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