tw-market-data

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

Annotations already declare this as read-only and idempotent, and the description adds meaningful behavioral context: the trail survives deploys, includes the reasoning basis, and reports coverage.missing. It also clarifies the limit is newest-first with a max of 200, going beyond 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?

The description is moderately concise and well-structured, with the core purpose front-loaded and a clear Args section. Some promotional phrasing and illustrative detail could be trimmed, but each part contributes useful context about the audit trail's value and interpretation.

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 has an output schema and only one simple parameter, the description is nearly complete: it explains what the log contains, durability, missing-record reporting, and parameter behavior. It does not describe the output shape in prose, but the output schema already covers that.

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 carries the full burden for the single parameter. It clearly defines limit as 'how many records to return, newest first (max 200)', adding both ordering semantics and a maximum value that the schema does not provide.

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 returns a durable audit trail of what resident agents have actually done, with specific examples of the basis behind actions. It identifies the resource and scope well, though it does not explicitly differentiate itself from sibling list tools like list_alerts or risk_read.

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 conveys when this tool is relevant: when you need to inspect the audit trail, including detecting agents that recorded nothing. However, it does not explicitly state when to use this tool instead of a sibling, nor does it mention alternatives or exclusions.

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 annotations, the description reveals that the tool only writes an audit record, has no order or funds path, and that execution happens elsewhere by a person. This is meaningful behavioral context that annotations alone do not provide.

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-loads the core purpose. The explanation about no order/funds path is useful context, though slightly verbose, but it still earns its place by preventing misuse.

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 only two simple parameters and an output schema, the description covers what the tool does, what it does not do, where parameters come from, and why the approver field is required. No essential information is missing for safe 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 fully compensates by explaining that action_id comes from list_pending_actions or proposed_actions and by emphasizing that approver is required because an unattributed approval is not an approval.

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 action ('Record a HUMAN's approval of a proposed action') and clearly distinguishes approval from execution: it 'does NOT execute the action.' This separates it effectively from other tools like list_pending_actions and delete_alert.

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 clearly explains the intended use: recording human approval, not performing the action. It also tells the agent where action_id comes from, but it does not explicitly name alternatives or conditions for choosing a different tool.

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 goes well beyond the readOnly/openWorld annotations by disclosing the citation guarantee, sentence-dropping behavior with dropped[] and status 'unverifiable', the unsupported_term response, and the no-fabrication rule. It also clarifies that this tool only explains and does not give advice, which is critical behavioral context.

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 long but densely informative, and every section earns its place: audience, sibling differentiation, citation guarantee, error behavior, and scope limitation. The main purpose is front-loaded in the first sentence, and bold headers make the structure skimmable.

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?

Even with an output schema present, the description explains the semantic meaning of claims[] and dropped[], the unsupported_term case, and the no-advice boundary. This is complete enough for an agent to call the tool correctly in the intended beginner-routing context.

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 provides only bare titles ('Question', 'As Of') and no descriptions, so the description carries the burden. It adds that question is a plain-language question with examples, and that as_of is optional and formatted YYYY-MM-DD; however, it does not explain the semantic effect of as_of (e.g., historical date context), which is a minor gap.

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?

First sentence states a specific verb ('Answer'), a resource ('plain-language question in Taiwanese-market vocabulary'), and a distinctive output trait ('sentence by sourced sentence'). It then explicitly differentiates from describe_dataset, search_filings, and query_dataset by naming which user type each suits, so an agent can select among 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?

The description explicitly says this is for beginners who do not know which dataset they want, and contrasts it with describe_dataset (table already named), search_filings (company disclosures), and query_dataset (returns rows). It also states honest unsupported-term behavior, leaving no ambiguity about when to call or not call this tool.

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 declare readOnlyHint=true and idempotentHint=true, which already signal safety. The description adds crucial behavioral context: the two-date distinction (event vs announced), the separation of elapsed dates into 'past' rather than discarding them, and a warning that scheduled dates are movable. These are non-obvious traits not captured by annotations, enriching the agent's mental model.

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 long but well-structured with bullet points and a warning. It front-loads the core purpose and then explains nuances. Every sentence serves a purpose—clarifying the two-date logic, the past separation, and exclusions. Slightly verbose for a simple sort tool, but the complexity of the date logic justifies the length.

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 output schema exists, the lack of return-value description is acceptable. The description covers when to use, how to interpret dates, and a caveat about schedule reliability. It doesn't mention what happens if rows is null, but the schema's default null implies it's handled. Overall, an agent would know exactly how to invoke this tool 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?

With schema description coverage at 0%, the description fully compensates for as_of and today: as_of filters on announcement date, today is the reference date in YYYY-MM-DD. rows is only called 'dated events', but given the tool's purpose and schema's additionalProperties:true, this is sufficient. It could name the field expected inside rows, but the context makes it 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 opens with a clear, specific verb and resource: 'Sort corporate dates into what is still ahead and what has already passed.' It immediately distinguishes itself from sibling tools by naming search_filings and query_dataset as different retrieval tools. The purpose is unambiguous and distinguishable without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when NOT to use this tool: 'NOT search_filings AND NOT query_dataset. Those retrieve disclosures and rows; this one only arranges dated corporate events on a timeline relative to now.' It also explains the nuanced as_of vs event date semantics, giving the agent a clear rule for when to call this tool and how to set parameters.

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 discloses important behaviors: missing values emit null so the line breaks rather than bridging, zeros are never substituted, data_gaps lists absent positions, and citation/inclusion_pointer travel with the spec. It also explains the rationale, which helps an agent trust the 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 organized with clear headers, emoji emphasis, and each sentence earns its place. It front-loads the most important fact ('draws, does not fetch') before explaining edge-case behavior and output metadata.

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 rendering tool with an output schema, the description covers the input source, the critical null-gap behavior, the proof-tracking output fields, and the caveat that this is not analysis. Nothing essential to calling the tool 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 0%, so the description must compensate. It names all five arguments and adds meaning to rows ('already fetched', output of query_dataset) and mark (allowed values), but x_field and y_field are left to be inferred from their names and the chart context. It is adequate but not fully detailed.

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 leads with a specific verb-resource pair: 'Turn rows you already fetched into a Vega-Lite drawing' and immediately distinguishes itself with 'IT DRAWS; IT DOES NOT FETCH.' This clearly identifies the tool's core function and separates it from data-fetching siblings like query_dataset.

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 says to hand it the output of query_dataset and explains why it never touches the database, which is strong guidance. It adds a when-not-to-use warning ('Rendering, not analysis'), though it does not name a specific alternative tool for analysis.

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 goes far beyond the annotations' safety hints. It explains the Merkle checkpoint_root, verify_url, signed reproducible_token, the point_in_time: false behavior, and the critical caveat that the citation proves which data was used but not that figures are correct. This is rich behavioral context that materially changes how an agent should interpret the tool's output.

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 longer than average, but the length is earned: it front-loads the core purpose, then uses bolded headers to explain when to use, what it proves, and what it does not prove. Some prose could be tightened (e.g., the multi-sentence scenario about reviewers in the future), but overall it is well-structured and scannable.

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 only one required parameter and an output schema, the description covers all operational concerns: parameter semantics, point-in-time behavior, verification semantics, and the limitation to preserve. Annotations cover the read-only and idempotent profile. Nothing an agent needs to call this tool 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 0%, so the description fully compensates. The Args section explains dataset with an example ('valuation'), as_of with format and omission guidance, and row_key with its conditional use case ('pin the citation to one specific row'). Each parameter gains meaning beyond the bare schema types and titles.

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: 'Produce a bibliographic citation for TWMD data — APA, BibTeX, and a re-verifiable token.' This clearly distinguishes the tool from siblings like get_inclusion_proof or query_dataset, which serve different purposes. The title 'Cite a served number' further reinforces the narrow scope.

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 explicit when-to-use guidance: 'FOR PAPERS, REGULATORY FILINGS AND ANYTHING A REVIEWER WILL RE-CHECK LATER.' It also explains when to pass as_of ('PASS as_of IF YOUR WORK IS POINT-IN-TIME'). It does not name specific sibling alternatives or provide exclusion criteria, but the intended context is clear enough for an agent to route correctly.

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 annotations, it explains point-in-time semantics (as_of and 'latest known, not today'), the cannot_see categories, checked_and_clear vs cannot_see, disambiguation behavior, self-fetching of nine datasets, licensing fallback, and read-only side effects. No contradiction with annotations; all consistent.

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?

Bulleted structure with bold labels makes the dense content scannable and front-loads the one-line summary. Each bullet carries substantive operational or behavioral guidance; slightly long but not padded.

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 that self-fetches nine datasets, the description covers preconditions, auth, licensing, edge cases, output semantics, and side effects. Since an output schema exists, omission of exact return shape is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds detailed meaning to as_of (disclosure timing, fallback to latest known) and gives ticker-resolution context (needs_disambiguation). It does not specify accepted ticker format or exchange suffix, but schema coverage is 0% and the description does real compensating work.

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 opening line defines an 'honest health check' of a stock covering growth, earnings quality, valuation, positioning, and red flags, and clarifies it is fact-gathering, not investment advice. This goes well beyond the title, but it does not compare itself to sibling tools, so it is clear without explicit differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: it is for fact-finding, explicitly not investment advice/prediction/target price, and says callers do not need to stage data with query_dataset first. It also states session identity requirements and that entitlement checks are unnecessary. It does not fully enumerate alternative tools for adjacent tasks.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds genuinely useful behavior beyond that: absent figures are reported as `available: false`, never filled with zero/previous period/dropped, and each cell names its own source. This goes well beyond the structured hints.

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 core purpose sentence is front-loaded, and the starred notes each carry meaningful behavioral guidance. The description is longer than minimal, but the added length is mostly purposeful, with only mild formatting weight.

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 an output schema exists and annotations cover safety, the description completes the picture: when to use it, what data gaps mean, per-cell source behavior, and argument constraints. An agent has enough to select and call the tool 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 carry parameter meaning. It does name all four arguments and clarifies the ticker count constraint and optionality of rows_by_ticker/as_of. However, metric names/formats and as_of semantics remain implicit, so the compensation is only partial.

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 and resource: 'Lay two to five named companies side by side on the same measures, gaps marked as gaps.' It clearly defines the tool's scope and distinguishes it from siblings by noting it requires companies to be specified upfront.

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 explicitly says 'NOT `screen` AND NOT `find_related`' and explains when those alternatives apply: screen finds symbols when you have none, find_related walks supply-chain links. It also warns that side-by-side figures are not ranking, which helps prevent misuse.

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 destructiveHint annotation, the description explicitly states cancellation is irreversible, re-arming requires creating a fresh trigger, and invalid ownership results in no action. This significantly enriches the behavioral context an agent needs before calling a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the first sentence conveys the core action, identifier, and permanence. Following sentences add necessary distinctions (opposite of set_price_alert, state-change vs list_alerts, irreversibility, ownership) without fluff.

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 one-parameter destructive tool with an output schema and explicit annotations, the description covers all critical context: what it deletes, how it identifies the target, that it is irreversible, and that ownership is enforced. 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?

Schema coverage is 0%, but the description compensates by explaining that rule_id identifies the trigger and that ownership matters ('Naming somebody else's rule id cancels nothing at all'). It could add more detail about the id format, but for a single simple string parameter this is sufficient.

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 ('Cancel'), a resource ('one armed price trigger'), and the identifier used ('rule id'). It also explicitly contrasts itself with set_price_alert and list_alerts, so the tool's purpose is unambiguous and differentiated from 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?

The description clearly positions the tool as the opposite of set_price_alert and notes that unlike list_alerts it changes state rather than reporting it. It also warns that naming someone else's rule id cancels nothing, which gives agents a concrete when-not-to-use condition.

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, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds useful output context by listing time-correctness rules and agent_hints, but does not describe behaviors like error handling or response shape; the output schema covers 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?

The description is one dense, scannable sentence with the main point front-loaded ('FULL semantics of one dataset') and key items listed compactly. The time-correctness warning is flagged with a star and 'read before backtesting', adding priority without bloat.

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 output schema and single required parameter, the description sufficiently explains what content is returned and when to use it. Nothing critical is missing for an agent deciding between this and similar data 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?

There is one parameter, dataset_id, and the description confirms it via 'Args: dataset_id' while 'one dataset' implies an identifier context. However, schema description coverage is 0%, and the description does not explain how to obtain or format a dataset_id, such as from list_datasets.

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 exactly what the tool does: it returns FULL semantics for one dataset, enumerating grain, fields, time-correctness rules, relations, agent_hints, and quant_use. This content set clearly distinguishes it from siblings like query_dataset or list_datasets.

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 trigger: read time-correctness rules before backtesting. It does not formally name alternatives or when-not to use it, but the 'before backtesting' context and semantic focus make the intended 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?

Although annotations already mark the tool as readOnly, idempotent, and open-world, the description adds substantial behavioral detail beyond them: the four possible verdicts, the critical warning that 'partial' is not 'resolved', the fact that ambiguous_field deliberately lists candidates without picking one, and that unknown_field means 'we do not have that column' rather than 'no data found'. It also directs the agent to read limitations for derived-versus-observed knowability dates. No contradiction with 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 long, but every section earns its place: the purpose, the sibling non-overlap, the verdict semantics, the limitations warning, and the parameter examples. It is front-loaded with the most important usage guidance and uses formatting (stars, verdict names, bolded warnings) to make the dense content scannable. None of the text is redundant with 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?

Given the tool's complexity, the description is remarkably complete. It covers when to use the tool, what each verdict means, how to handle ambiguous fields, what limitations to consult, and what each parameter represents. The presence of an output schema relieves it of explaining return-value structure, and the description instead addresses the conceptual traps that would otherwise lead an agent astray.

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 carries the full burden of explaining parameters, and it does so well. Each parameter gets a concrete definition and example: ticker as '2330', field as 'close' or 'revenue', date as YYYY-MM-DD, and dataset as a disambiguation pin. The dataset parameter's role in the ambiguous_field case is also explained, which is exactly the semantic insight an agent needs beyond the raw 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 the exact question the tool answers — 'Where did this number come from, and when could anyone have known it?' — then states the precise operation: given a ticker, field, and date, it names the dataset, knowledge column, and applicable as_of rule. It also distinguishes itself from the sibling provenance tools by explicitly stating what it is not, so an agent can confidently tell it apart from get_inclusion_proof and cite_this.

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 an explicit trigger condition: 'Use it whenever you are about to state a number as fact.' It also names the two sibling provenance tools and explains why they are not substitutes, each with its own one-line purpose. It even prescribes the next step for ambiguous_field results — re-ask with dataset= — so the agent knows exactly when and how to adjust its invocation.

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 read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context by explaining that the tool traverses a knowledge graph and what each input mode returns, including the '+why' reasoning for joinable datasets.

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 with the core operation, followed by two scannable parameter bullets and a concise args line. Every sentence contributes meaningful 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 low parameter count, the read-only annotations, and the presence of an output schema, the description covers what an agent needs to select and invoke the tool correctly. It explains both input modes, their purposes, and example values, leaving no critical 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?

Schema description coverage is 0%, so the description carries the full burden. It explains each parameter's exact output, gives concrete examples, and clarifies that the arguments may be used together or separately ('and/or').

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 ('Traverse the knowledge graph') and the resource it operates on, with per-parameter expected outputs. It does not explicitly differentiate from sibling tools such as supply_chain_read or query_dataset, so differentiation is left implicit.

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 clear context for when to use the tool: 'to plan multi-table analysis' via dataset_id and 'supply-chain reasoning' via ticker. It does not name alternative sibling tools or state when not to use this tool, 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?

Annotations already declare readOnly/openWorld/idempotent behavior, so the bar is lower. The description adds valuable behavioral context beyond annotations: it reveals that rejected backtests are retrievable and that out-of-namespace run_ids return 'not found' rather than an error. No contradiction with 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?

Three concise sentences with the core purpose front-loaded, followed by the namespace caveat and parameter guidance. Every sentence adds useful information with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter retrieval tool with an output schema present, the description covers everything an agent needs: how to identify the run, where the handle comes from, and the namespace visibility behavior. No critical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden for the single parameter. It compensates well by explaining the format (`twmd_bt_…` handle) and provenance (returned by run_backtest), adding meaning far beyond the bare schema 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?

States a specific verb ('Retrieve'), resource ('previous backtest'), and key ('run_id'), and clarifies it returns the full record including rejection reasons. This clearly distinguishes it from siblings like run_backtest, replay_backtest, and list_backtests.

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?

Provides clear context for when to use the tool—retrieving a prior backtest by run_id—and adds an important namespace exclusion (others' run_ids are simply not found). It does not explicitly name alternative tools, but the usage context is strong and unambiguous.

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 it read-only/idempotent/non-destructive, and the description adds substantial extra behavior: constants are read live from the server, unconfirmed routes are refused, Python output is compiler-checked, JS is structure-checked only, and credentials are obvious placeholders. This is exactly the kind of context that prevents misuse.

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?

Main purpose is front-loaded, and each starred paragraph earns its place by addressing a distinct operational concern. It is longer than minimal, but the length is justified by the need to prevent plausible-looking broken client code.

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 thoroughly covers behavior and edge cases, and an output schema exists, so return structure need not be spelled out. The only notable gap is the meaning and allowed values of the required 'intent' parameter, which an agent would need clarified to reliably invoke the 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?

The schema has no descriptions (0% coverage), so the description must carry parameter meaning. It lists 'intent, language (python/javascript), ticker, optional as_of' and clarifies language options and as_of optionality, but it never defines what an 'intent' is or what format as_of should take. This is partial compensation, not full.

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?

Description opens with a specific verb and resource: 'Emit a copy-pasteable HTTP snippet wired to the real endpoint, header and parameter names.' It also explicitly distinguishes this tool from siblings ('FOR WRITING YOUR OWN CLIENT, NOT FOR GETTING DATA'), so an agent can select it confidently.

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 when to use this tool ('if your program needs to ask over HTTPS') and contrasts it with all other tools ('Every other tool here answers a question; this one hands you source code'). No ambiguity remains about whether to use this for data retrieval.

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 it read-only/idempotent/non-destructive; the description goes further by disclosing the deliberate path-not-boolean response, the scope of the proof (integrity/origin, not correctness), and the existence of three statuses. However, it only enumerates two of the three statuses, leaving one possible response state undefined.

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 purpose and compact section labels make the important caveats easy to find, and the prose is dense but justified for a verifiability tool. The main structural blemish is that 'THREE STATUSES' is followed by only two listed statuses.

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?

Strong coverage of return semantics and caveats, and the output schema likely fills field-level details. The main gap is the unlisted third status and any related edge behavior, which an agent could encounter when calling the tool with an invalid or older snapshot_version.

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 carries parameter documentation: dataset is exemplified, row_key is defined as the logical key joined by '|' with an example, and snapshot_version is explained as omittable for the most recent checkpoint. This meaningfully compensates for the bare 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?

Clearly states a specific action ('Prove a row was in the snapshot TWMD published'), names the returned artifacts (Merkle sibling path, signed root, checkpoint), and explains why a path is returned rather than a boolean. No sibling tool shares this responsibility, so it is easy to distinguish from the rest of the tool list.

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?

Explains when to use it (proving inclusion in a TWMD snapshot) and, importantly, when not to rely on it ('It does NOT prove the numbers are correct'). It also gives the verification workflow, though it does not explicitly discuss alternative sibling tools or exclusion conditions.

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 adds meaningful behavioral context: the report must be from the caller's own run, and other users' reports will simply not be found. It also explains the provenance of the research_id, which informs how the tool behaves when given an invalid or foreign ID.

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 compact sentences carry the behavior, scope, and parameter semantics with no filler. The key constraint ('YOUR previous research') is front-loaded, and the argument explanation is immediately actionable.

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 single-ID read operation, the description, combined with strong annotations and an output schema, leaves no critical gap. The agent knows what to call, how to obtain the identifier, and what to expect in terms of access scope.

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 does by explaining that research_id is the identifier returned by run_research at the start of a run, giving the agent a concrete way to source the value. It stops short of providing format examples, but the provenance guidance is highly useful for a single-parameter tool.

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?

Description uses a specific verb ('Retrieve') and identifies the exact resource: the user's own previous research reports. It clearly distinguishes itself from run_research by focusing on past reports, and even notes that others' runs are not found, which sharpens the scope.

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 clearly implies this tool is for retrieving already-created reports, not for running new research. It references run_research as the source of the identifier, which gently points toward the workflow without explicitly listing when-not-to-use 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 mark the tool read-only, idempotent, and non-destructive, so the description's emphasis on 'arms nothing and cancels nothing' adds some redundancy but reinforces the safety profile. It adds genuinely useful behavioral context by stating that the results are scoped to the caller's own armed triggers and that another customer's triggers are not visible.

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 core statement is front-loaded and immediately understandable, with the additional side-effect and scoping details placed in a supporting sentence. It is slightly wordy with repetition of 'armed' and the metaphorical 'thresholds you asked to be watched,' but every major piece of information earns its place.

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, read-only listing tool with rich annotations and an output schema available, this description is complete. It covers what is returned, the ownership scope, the armed-status information, and the relevant alternative tools, so an agent has enough context 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?

The input schema has no properties, so there are no parameter semantics to document and schema coverage is complete by definition. The description still adds meaningful scope-level semantics by explaining that the returned inventory consists of thresholds the caller personally armed.

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: 'Show the price-trigger rules you have armed, and whether each is still armed.' It clearly identifies what is listed and the state information included, and it distinguishes itself from set_price_alert and delete_alert by naming them as the tools that perform those actions.

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 explicitly positions this as a read-only inventory and contrasts it with `set_price_alert` (arms) and `delete_alert` (cancels), making it clear when to use this tool versus those alternatives. It also clarifies that another customer's triggers are not visible, which helps an agent understand the scope and avoid expecting cross-account 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond annotations by explicitly stating 'never re-computes anything' and describing the output as an index of ids and headline metrics. This reinforces and enriches the safety profile without contradicting it.

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 front-loaded with the core purpose, then usage guidance and alternatives, and ends with a compact args line. Every sentence adds distinct value with 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 no required parameters, a simple index operation, and a true output schema, the description covers everything an agent needs: what the tool returns, when to use it, what it never does, and how it differs from related tools. No significant gap remains.

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 names the two parameters ('optional strategy_id filter, limit') but does not elaborate on their semantics — e.g., that limit caps the result count or that strategy_id narrows to a specific strategy's runs. Some meaning is inferable from names and defaults, but the description does not fully carry the burden.

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?

Description states a specific verb ('Browse an INDEX') and resource ('past backtest runs'), and clarifies scope: 'ids and headline metrics only, no re-execution.' It clearly distinguishes itself from siblings by saying 'This is the catalogue, not any of those three.'

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 when you want to find a run whose id you have forgotten') and names three alternatives with their distinct purposes: run_backtest, get_backtest, and replay_backtest. This leaves no ambiguity about when to select this tool.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns summaries (id / 中文名 / category / tier / one-line description) and frames it as a discovery entry point, but it doesn't disclose behaviors such as pagination, ordering, locale, or data volume. With annotations in place, the added context is useful but not rich, meriting a 3.

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 tightly writtgen: one sentence for purpose, one for return fields, one for usage, followed by a compact Args block. Every sentence contributes a distinct piece of information and the args are formatted clearly with examples. There is no fluff or 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 low complexity (2 optional params, no nested objects), the availability of an output schema, and annotations that cover safety/idempotence, the description covers purpose, returned fields, parameter semantics, and usage sequence. It is complete enough for an agent to invoke it correctly without further inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the schema only shows two nullable string parameters with defaults, so the description bears the full burden of explaining them. It does so excellently: for category it lists concrete example values with Chinese labels, and for tier it explains the 'optional minimum plan' and lists valid plan names. This gives an agent exactly what it needs to construct valid filter arguments, far beyond the raw 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 states a specific verb and resource: 'List available Taiwan-market datasets' and explicitly lists the returned fields (id / 中文名 / category / tier / one-line description). The phrase 'discovery entry point' and 'Use this first' clearly sets it apart from siblings like describe_dataset or query_dataset, so an agent can distinguish it immediately.

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 clear context, calling the tool the 'discovery entry point' and instructing agents to 'Use this first to find the right data'. This tells when to use it, but it does not explicitly enumerate alternatives or say when not to use it. It also doesn't name sibling tools like describe_dataset or try_sample as follow-up options, so it falls just 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?

Beyond the readOnly/idempotent annotations, the description discloses deliberate inclusion of rejections, trial counts, the meaning of coverage.missing as untested rather than rejected, and that accepted factors are findings with run_ids rather than allocations. These are meaningful behavioral details an agent could not 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?

The core purpose is front-loaded and each paragraph covers a distinct semantic point. Some rationale prose is longer than strictly necessary for executing the call, but it is not filler and supports correct interpretation.

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 list tool with an output schema already available, the description covers scope, ordering, limit cap, and the special semantics of rejections and missing coverage. 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?

The schema only defines an integer limit with a default, but the description adds that limit controls how many verdicts to return, that ordering is newest-first, and that 100 is the cap. Since schema description coverage is 0%, the description fully compensates.

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 resource and action: it returns factor-search verdicts for the caller's namespace, including rejections. This distinguishes it from sibling list/get tools by emphasizing the overnight factor-search scope and the deliberate inclusion of rejected findings.

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 context: use this when you want the full set of overnight factor-search verdicts, not just accepted ones, and when you care about the acceptance rate as a quality gate. It does not explicitly name alternatives or exclusion conditions, 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 declare readOnlyHint=true and destructiveHint=false. The description adds valuable beyond that by explicitly stateing 'Nothing here has been executed or ever will be by this system. These are proposals.' This prevents a common misinterpretation that listing reveals executed or executable actions. No contrdiction with 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: two short sentences, purpose first, with the crucial non-execution clarifiation second. Every sentence adds value and there is no fluf or repetition of schema/annotation 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 no-parameter list tool with robust annotations and an output schema, the description is complete. It tells an agent what the list contains, that the items are proposals only, and that the system will never execute them. Nothing important is missing for correct tool selection.

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 zero parameters, so the description has no parameter burden. The schema coverage is vacuously 100%, and the baseline of 4 for a zero-parameter tool applies. The description adds the relevant context about what the returned items represent.

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?

Description states a clear verb ('List') and specific resource ('financial actions proposed by your research runs that are waiting for a human decision'). This differentiates it from siblings like approve_action by emphasizing these are proposals awaiting human input. It precisely defines what the tool returns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use: when an agent needs to see financial actions proposed by research runs that have not yet been decided on. It does not explicitly name alternatives or exclusions, but the 'waiting for a human decision' phrasing makes the intended use context unmistakable.

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 carry readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description aligns (read-only, does not write). Beyond annotations it adds genuine value: the output is fact-collection not advice/prediction and carries does_not_prove; WorldBank-type sources get retroactively revised so historic-year numbers differ from what was seen before, flagged via pit_notes; subject is fixed to TW_MARKET. The retroactive-revision disclosure is substantial behavioral context. No contradiction with 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?

Front-loaded with the core purpose and organized with ★ bullets, but verbose: the fact that it does not take a ticker is repeated three times ('所以它不收 ticker', '它不收 ticker 因為主體是整個市場', '不收 ticker'). Several lines re-state what the schema and annotations already convey (single optional arg; read-only), adding length without new 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?

Thorough for a simple read tool: an output schema exists so return format is covered externally, and the description covers the subject scope (market vs ticker), the honesty wrapper (does_not_prove), the point-in-time revision caveat, preconditions (identified session), and side effects. Only minor gap is as_of semantics, mentioned under parameter scoring.

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 carries the burden. It correctly states the only argument is as_of (optional) and that it does not take a ticker. However, it never explains what as_of actually controls (e.g., the point-in-time date for which regime state is read) or any date format semantics. This partial compensation earns a 3, not higher.

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 specific verb+resource: reads the 總經 (macro) regime — business cycle signals, rates, yield curve, FX, capital flows. Explicitly distinguishes itself from single-stock tools ('這支講的是整個市場,不是任何一檔個股'), scoping the tool precisely. The example question ('現在景氣循環在哪個位置' is this tool) anchors the purpose concretely.

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 a clear usage context: use when asking about the market-level business cycle, not about an individual ticker. States it does NOT take a ticker and is not for single-stock questions. Does not explicitly name sibling alternatives like query_regime or positioning_read as the alternative route, so the exclusion is implied rather than named.

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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is well established. The description adds useful behavioral context: the watchlist is user-maintained and the read reflects current state, not a historical search. No contradiction with 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 tight and front-loaded. The first sentence states the core action, the middle distinguishes from related tools, and the final note covers the parameter. No filler or 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?

With one optional parameter, rich safety annotations, and an output schema present, the description covers everything needed to invoke the tool correctly. It explains scope, alternatives, and the key argument, leaving no critical 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?

Schema coverage is 0%, so the description must carry parameter meaning. It does: 'key — the roster's name, default "default"' clarifies that key identifies a named watchlist and gives the default. This is sufficient for a single simple optional 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?

The description opens with a specific verb and resource: 'Read the tickers on one named watchlist,' and adds temporal scope ('as it stands right now'). It clearly separates this tool from siblings memory_search and list_alerts, so an agent can distinguish it without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly contrasts the tool with memory_search ('digs through everything you ever recorded') and list_alerts ('price triggers rather than symbols you are following'), giving the agent clear when-to-use/when-not-to-use guidance. The default key behavior is also stated.

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

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

Annotations already convey read-only, open-world, idempotent, and non-destructive behavior, and the description richly supplements them: it defines the three status outcomes, explains when result is absent, identifies result_hash as authoritative in too_large cases, and clarifies what not_found means. This is exactly the behavioral detail an agent needs beyond 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 front-loaded with the core action and then organized into a compact status list. The philosophical aside about two implementations of 'replay' adds useful rationale but is slightly less essential than the rest.

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 only one parameter, a rich output schema, and strong annotations, the description fully covers invocation semantics, status outcomes, parameter origin, and behavioral guarantees. Nothing an agent needs to call this safely and interpret results 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?

The schema provides only a bare string field, so the description carries full weight. It explains the twmd_q_… format and specifies that the id comes from a remembered finding's citation, giving the agent everything needed to source and pass the parameter correctly.

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 pair: re-run a remembered query by its twmd_q_… id through the replay store. It clearly differentiates from a generic replay concept by noting it uses the read API's own replay store and never re-executes via another route, so it stands apart from siblings like replay_backtest.

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 clear context: use this to fetch the data behind a remembered finding's citation so the finding is checkable. It also communicates an important boundary—never re-executes the query by another route—but it does not explicitly name sibling tools or state when-not-to-use conditions in a direct 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?

The description adds meaningful behavioral detail beyond the annotations: nothing is overwritten, both rows survive, duplicate saves are no-ops, and findings without source_query_ids are refused. This aligns with idempotentHint=true and provides operational expectations the annotations alone 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?

The description is well-structured and front-loaded with the most important semantic guarantee, followed by a concise argument-by-argument breakdown. Every sentence adds value, and there is no fluff or 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?

Despite having six parameters and nested content, the description leaves no significant gap: it covers all parameters, required conditions, behavioral guarantees, and refusal criteria. The output schema exists, so return-value documentation is unnecessary.

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 fully compensates by explaining each parameter: kind, content, key, as_of, source_query_ids, and agent_id. It also explains why key and source_query_ids are conditionally required, which is essential for correct invocation.

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 'Remember something, with its sources and its knowledge time,' which clearly states a specific verb and resource. It further clarifies the memory kinds and distinguishes saving from the read/query siblings like memory_search and memory_get_watchlist.

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 strong usage guidance on required parameters per kind, such as key being required for factor_def/watchlist and source_query_ids required for finding. It does not explicitly contrast with sibling read tools, but the save-vs-retrieve distinction is obvious from the wording and sibling 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 mark the tool as read-only and idempotent, and the description adds rich behavioral context: results carry source_query_ids, valid_from/valid_to, as_of knowledge-time, and a recall block showing which model and filters produced the answer. It also reveals the current-only default behavior. There is no contradiction with 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 well structured: the core behavior is front-loaded, the provenance note is compact, and the Args list is clean and information-dense. Every sentence adds value without repeating 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?

For a 7-parameter search tool with zero schema descriptions, the description covers behavior, provenance, temporal semantics, defaults, and filtering options, and an output schema exists to cover return shape. The only meaningful gap is the undocumented limit parameter, which leaves its exact cap semantics ambiguous.

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%, but the description compensates by explaining six of seven parameters, including the allowed values for kinds and the temporal semantics of as_of. Only limit is left undocumented, so the description does not fully close the parameter-semantics gap.

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 resource ('your own memories') and the operation (search via 'hybrid semantic + exact-term'), making the tool's purpose unmistakable. The provenance and as-of features further distinguish it from sibling memory tools such as memory_get_watchlist and memory_replay_query.

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 concrete guidance: use as_of for any point-in-time lookup, use key when the stable name is known, use agent_id to narrow scope, and use include_superseded for the audit view. It does not explicitly name alternatives or state when not to use this tool, so it stops short of fully explicit when/when-not 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?

Annotations already declare read-only/idempotent, but the description adds substantial behavior: point-in-time semantics with as_of, a cannot_see taxonomy (not queried / query failed / distribution rights missing), a hard rule never to estimate broker-level positions, and license-failure handling. This goes well beyond the annotation hints and gives the agent a faithful model of the tool's 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 dense but each bullet earns its place: purpose, point-in-time, cannot_see, preconditions, arguments, return envelope, and side effects. The structure uses visual anchors and front-loads the core purpose, making it scannable despite its length.

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 read-only tool with an output schema, the description is remarkably complete. It covers invocation preconditions, argument semantics, visibility limitations, licensing behavior, return shape, and side effects. There is no critical missing context an agent would need to call this tool 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?

With 0% schema description coverage, the description must carry parameter meaning. It explains ticker with an example ('2330') and describes as_of as an optional knowledge time boundary with point-in-time lag semantics. The only minor gap is that no exact date format or validation rules for as_of are provided, but the semantics are clear enough for correct invocation.

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 concrete resource ('籌碼結構') and names the specific read operation, making it clear this tool surfaces institutional positioning data. It distinguishes itself from siblings like query_dataset by stating rows do not need to be prepared via query_dataset and by framing output as fact compilation with does_not_prove.

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 explicit preconditions: an identified session is required, data is self-fetched and does not need query_dataset, and unlicensed datasets should be routed to cannot_see rather than failing the call. It also states what the tool is not (investment advice, prediction, target price), providing clear when-to-use and when-not-to-use 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?

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, yet the description adds substantial value beyond them: the disclosure-date filtering semantics for non-PIT datasets, the exact meaning of coverage.missing (with an explicit 'never estimate/interpolate/carry forward' prohibition), the attribution requirement tied to query_id, and the subtle freshness caveat that null staleness is NOT freshness. These are safety-critical behaviors no annotation conveys. No contradiction with annotations — querying is consistent with readOnlyHint and openWorldHint.

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?

Heavily structured with ★-marked sections, an Args block, a Returns block, and a concrete Example — well front-loaded with the PIT point, which is the most important behavior. It is verbose for a tool description, but given the safety-critical semantics (missing-value handling, provenance attribution) virtually every sentence earns its place. Minor redundancy in the provenance paragraph keeps it from 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?

For a complex, safety-critical read tool, the description is remarkably complete: it covers PIT semantics, missing-value behavior, provenance/attribution, freshness interpretation, parameter formats, and a worked example. An output schema exists to document the return structure, so the description need not enumerate fields. The only gap is the unexplained cursor parameter; otherwise an agent has everything needed to call it correctly and interpret results faithfully.

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 documentation burden, and it does: dataset_id (via list_datasets), tickers (with concrete examples), start/end ('YYYY-MM-DD' range), as_of (knowledge-time cutoff), and limit (<=5000). This covers 6 of 7 parameters; cursor is never explained, which is the sole gap. It also documents the full return shape. Strong compensation for zero schema coverage, just one undocumented 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?

The description opens with a precise verb+resource: 'Query rows with built-in look-ahead protection,' which identifies the operation, the target (datasets), and the distinguishing trait (point-in-time safety). It clearly differentiates from query_regime and other read tools, and cross-references list_datasets for dataset_id and replay_query for verification. An agent can tell exactly what this tool does and how it differs from sibling data 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?

Explicit usage conditions are given: pass as_of for backtesting/agent-learning, omit it only for present-day lookups ('warned'), and reference sibling list_datasets for dataset_id and replay_query for later verification. It does not enumerate exclusions against every sibling read tool (e.g., describe_dataset, query_regime), but the when-to-use guidance for the critical parameter is clear and actionable.

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 goes well beyond the annotations by disclosing that data is as-revised rather than point-in-time, that `as_of` is refused, that the source has a single current row per month with no publication date, and that using date ranges ending at `as_of` still creates look-ahead. This is exactly the kind of behavioral context an agent needs.

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 longer than average, but every bullet earns its place: the revised-data warning, the `as_of` refusal and its rationale, and the explicit backtest-context boundary. The most important caveat is front-loaded, and the structure makes the warnings easy to absorb.

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 output schema is present, the description does not need to explain return values. It covers the data revision status, the refusal behavior, the look-ahead trap, and the intended use case, making the tool safe and unambiguous to invoke.

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 carries the burden for parameters. It adds crucial meaning for `as_of` and for date-range behavior, but it does not explicitly explain the formats or semantics of `start`, `end`, or `limit`, leaving those to be inferred from their titles and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The title and description clearly identify the resource: the Taiwan business-cycle light (NDC monitoring indicator) as a monthly series. It communicates the core function well, though it never explicitly names or contrasts itself with the similarly named sibling `macro_regime_read`, so some differentiation is left implicit.

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 explicit usage context: use it for market context, not as a backtest input, and do not work around the `as_of` refusal by date-range tricks. It does not name an alternative tool to use for backtest inputs, so the guidance is clear on when not to use it but less explicit about what to use instead.

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?

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds significant behavioral context: the SQL cutoff is applied before the row limit, `as_of` absence disables point-in-time semantics and warns, the tool deliberately omits sentiment/scores, and the corpus may be small or title-only. It fully discloses caveats the agent needs to interpret results safely.

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 long but every section earns its place: it opens with the core purpose, then gives alternative routing, point-in-time mechanics, anti-patterns, corpus caveats, and parameter semantics. Bolded lead-ins and bullet-like organization make it scannable, and there is no redundant or filler content.

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 read-only tool with an output schema available, the description covers all necessary call decisions: what it returns conceptually, how to keep reads bounded, what caveats affect interpretation, and how to handle missing results. The presence of an output schema reduces the need to describe return fields, and the description fills all other gaps around usage and interpretation.

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 it succeeds. Every parameter is given meaning and format: `source` with examples, `tickers` with example values, `as_of` as YYYY-MM-DD knowledge cutoff, `since` as lower bound on the same column, and `limit` with a warning to keep it small because these are whole documents.

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: read the full text of filings and announcements, with proof links and a knowledge cutoff. It explicitly distinguishes itself from search_filings by contrasting whole documents vs fragments. This makes the tool's purpose unambiguous and differentiates it from a closely related sibling.

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 explicitly names `search_filings` as the alternative and explains why this tool should be used instead when full text is needed. It also provides clear conditions: point-in-time behavior requires `as_of`, read `corpus_reality` before concluding anything, and a missing ticker means nothing is held, not that no disclosure occurred. This is thorough when-to-use and when-not-to-use 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?

Annotations already signal read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: it reports discrepancies, does not smooth over changes, and identifies possible causes (engine version or data restatement). This helps the agent set expectations about the tool's output philosophy.

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 with the core purpose. Every sentence contributes value, including the behavioral note about not smoothing over discrepancies and the argument hint.

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 tool with rich annotations and an output schema, the description covers the purpose, behavioral expectations, and relevant interpretation of results. There is no prerequisite or edge-case information that an agent would critically need here.

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% and the description only states 'Args: run_id' without explaining what run_id identifies or any constraints. The main text implies run_id refers to a stored backtest, but the description does not compensate for the missing schema documentation.

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 ('Re-run') and resource ('stored backtest') and states the exact purpose: report whether it still produces the same numbers. It also clarifies scope with 'Same spec, same as_of, same data questions,' which distinguishes it from running a new backtest or fetching current results.

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 clearly implies when to use this tool: to verify reproducibility of a stored backtest and detect drift in engine behavior or data. It does not explicitly name alternatives like run_backtest or get_backtest, but the context is clear enough that an agent would know this is for replaying an existing run.

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/non-destructive annotations, the description discloses significant behavior: it names unpriced positions instead of silently assessing a partial portfolio, breaches produce proposals that require human decisions, approving a proposal records the decision and executes nothing, TWMD has no order path, and pricing is point-in-time official data. This is far richer than annotation-only disclosure.

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 front-loaded with purpose, uses compact paragraphs and labeled Args, and every sentence adds functional value. The caveats about unpriced positions and the no-order-path behavior are important, not padding.

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 rebuild the return structure. It covers input formats, defaults, key behavioral caveats, the proposal/approval workflow, and the lack of brokerage integration, giving an agent enough to invoke the tool correctly in context.

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 succeeds. It gives the exact positions format with an example, clarifies these are user-stated holdings, defines as_of as a YYYY-MM-DD knowledge cutoff with default behavior, and explains max_position_weight and max_drawdown as fractions with concrete examples.

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 first sentence states a specific verb ('Measure'), a specific resource ('a portfolio you state'), and the conditions ('against limits you state', 'on official point-in-time prices'). It clearly conveys what the tool does and implicitly distinguishes it from account-level risk reads by emphasizing user-supplied holdings.

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 clear context for when to use it: for assessing a stated portfolio against stated limits, with an explicit warning that nothing is read from a brokerage account because no connection exists. It does not mention sibling tools by name or give explicit when-not-to-use conditions, 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context beyond those: it says output is factual, not advice/prediction, and carries does_not_prove; it distinguishes checked_and_clear from cannot_see (open-world semantics); it states side effects explicitly. No contradiction with 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 dense but well-structured with bullet points and front-loaded scope. Each bullet adds distinct value (differentiation, output semantics, non-advice, args, returns, preconditions, side effects). The ★ and bold formatting is stylistic but not wasteful. It could be tighter, but nothing is redundant.

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 output schema exists (not shown), the description explains the output semantics (concerns vs checked_and_clear) and mentions does_not_prove. It states preconditions and side effects. It does not address error handling or authentication beyond 'identified session', but for a read-only risk tool it is largely complete.

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 lists the parameter names and marks as_of as optional, with an example ticker. It does not explain what as_of means (e.g., date format, cutoff behavior) or how it affects results. This is minimal compensation for an undocumented 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 precise scope: event and market structure risks (implied volatility, attention disposal, penalties, short selling restrictions, factors). It immediately differentiates from risk_assess by explicitly stating position concentration and drawdown are not here. The verb 'read' matches the tool name and the resource (risk events) is concrete.

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 names risk_assess as the alternative for position concentration/drawdown, telling the agent which sibling to choose instead. It also clarifies the meaning of checked_and_clear vs cannot_see, which guides interpretation. Preconditions (identified session, self-fetching) are stated, and it reinforces read-only behavior.

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 annotations, it reveals that as_of is structurally enforced so the run cannot peek ahead, that failed runs are returned REJECTED with reasons rather than hidden, that results include query_ids and anti-overfitting checks, and that it places no orders. These are concrete behavioral traits not derivable from readOnly, idempotent, or destructive hints. No contradiction.

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 structure is front-loaded: purpose, behavior, then a compact Args list, then a short disclaimer. The Args block earns its length for an 11-parameter tool. Minor blemish: 'the測試期間' mixes languages and the first paragraph slightly overlaps with the 'Results arrive...' sentence, so it is not a perfect 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?

For a complex 11-parameter tool, the description is essentially complete: all meaningful parameters (except label) are covered with semantics and constraints, the no-default as_of requirement is explicit, rejection behavior is described, and the output schema covers return detail. It leaves almost nothing an agent needs in order to call the tool 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?

With 0% schema description coverage, the Args block compensates fully: it gives examples for strategy_id, date range meaning and the end <= as_of constraint, required no-default status for as_of, conditional tickers behavior, universe_kind options, rebalance values, cost_bps unit, and params format. Only label is not explained, a low-stakes 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?

The description opens with a specific action (run) on a specific resource (a point-in-time backtest) and names the output (run_id, metrics, sources, honesty checks). It is easy to tell apart from research/recipe tools, but it does not explicitly contrast with sibling tools like get_backtest or replay_backtest, so it stops short of full 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case — run backtests to measure historical strategy performance — and says 'This measures history.' It also gives conditional parameter guidance (tickers required for explicit universe) and invariants like end <= as_of. However, it never states when to prefer this tool over siblings like run_research, run_recipe, or replay_backtest, or when not to use it.

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 behavior, but the description adds substantial non-obvious behavior: skipped symbols are listed with reasons rather than silently omitted, missing inputs are never zero-filled, the routine is arithmetic over supplied rows rather than a trading view, and it composes rather than fetches. This goes well beyond what annotations and schema can 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?

The description is long but deliberately structured with distinct bullet points and warnings. It front-loads the core purpose and then uses each section to add operational context. Some lines are emphatic to the point of verbosity, but every section contributes behaviorally relevant information rather than padding.

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 six parameters, existing output schema, and rich annotations, the description covers the important contextual ground: what the tool runs, where rows come from, how skipped symbols are reported, how as_of is inherited, and the zero-substitution hazard. The main residual gap is full semantic detail for a few parameters, but the description is strong enough for an agent to invoke the tool correctly in most cases.

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 parameter-semantics burden. It names all six arguments and gives real meaning to recipe, rows, and as_of, plus a warning about zero substitution. However, today, top_n, and min_yield are left mostly to inference; there are no per-parameter definitions beyond routine names and defaults in the schema. This is helpful but not complete.

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: 'Replay a saved multi-step routine over rows you fetched.' It also names the three concrete routines and explicitly contrasts itself with fetch-style tools: 'IT COMPOSES, IT DOES NOT FETCH. Rows come from query_dataset.' This makes the tool's role unmistakable and distinguishes it from siblings like query_dataset and run_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?

The description gives clear context on when to use the tool: after fetching rows via query_dataset, and it warns that a saved routine is not a trading view. It also explains as_of inheritance, which sets expectations about the call chain. It does not explicitly enumerate alternatives such as run_backtest or run_research, so the exclusion is mostly implied rather than fully 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?

Beyond the annotations, the description discloses the role sequence, query_ids propagation, risk reporting placement, limitation handling, memory-driven skipping of rejected hypotheses, the anti-overfitting gate, and the explicit 'places no orders and moves no money' safety boundary. This is rich behavioral context that the annotations alone do not provide, and it contradicts nothing.

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 front-loads the core purpose, then adds compact behavioral notes and a clean Args block. Despite its length, every sentence earns its place by conveying operational, safety, or parameter-level detail needed to invoke the tool correctly.

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 six-parameter tool with no schema descriptions, the description covers invocation constraints, pipeline behavior, safety boundaries, and limitation handling. An output schema exists for return details, so nothing critical is missing for an agent to select and call this tool 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 carries the full burden of explaining parameters. It does so thoroughly: prompt is the only instruction channel, as_of is the required knowledge cutoff, tickers is optional with a point-in-time alternative, start/end has a constraint, and max_backtests is a cost-control cap.

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 first sentence uses a specific verb ('Run') and resource ('multi-agent research pass') and immediately promises a structured, sourced report. The six-role pipeline further distinguishes it from siblings like get_research and run_backtest, which are more targeted 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?

The description gives clear operational guidance: when to omit tickers for a survivorship-safe universe, why as_of is required, and that end must not be after as_of. It does not explicitly name alternative tools or state 'use X instead of Y,' but the context strongly implies when this multi-agent research pass is appropriate.

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 readOnly and idempotent, and the description adds valuable behavioral detail: thresholds are echoed in applied[], unrecognized phrases surface in unparsed[] rather than being silently invented, and missing values are excluded rather than treated as passing. This goes well beyond the annotations and sets accurate expectations.

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 front-loaded with the core purpose and uses bold markers to structure each distinct piece of guidance. Though longer than a minimal description, every block earns its place by adding behavioral disclosure, missing-data semantics, or sibling disambiguation.

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 annotations, output schema, and sibling list, the description covers the invocation path, return behavior via applied[] and unparsed[], missing-value handling, and alternative routing. No critical information needed to select or call the tool correctly is absent.

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 parameter-meaning burden. It defines conditions as 'plain words' / spoken shortlist description, as_of as optional, and rows as optional pre-fetched rows. It does not detail as_of format, but it provides enough semantic grounding for correct invocation.

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 first sentence names a specific transformation: turn a spoken shortlist description into explicit numeric cut-offs and show them. It also explicitly distinguishes itself from query_dataset and compare by describing what those do and when this tool is appropriate, so an agent can tell them apart.

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 explicitly states this tool is for when you have no symbols yet, only a description of what you are looking for. It names query_dataset as the alternative when symbols are already chosen and compare for named symbols, giving clear when-to-use and when-not-to-use 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?

Annotations already declare readOnly/openWorld/idempotent, and the description adds critical behavior beyond those: SQL-level point-in-time filtering before ranking, `meta.as_of_applied` reflecting the actual cutoff, look-ahead unsafety without `as_of`, coverage.missing semantics, and the explicit caveat that ranking is similarity, not evidence. This is model-helpful transparency.

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 long but well-structured with bolded callouts, an Args section, and a Returns section. Every section adds meaning, though some points (e.g., look-ahead warning, not investment advice) are repeated across prose and meta-field notes, making it slightly heavier than strictly necessary.

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 semantic search tool with an output schema, the description is complete: it covers result fields, meta warnings, provenance, coverage missing semantics, and common pitfalls like empty results meaning 'not indexed' rather than 'no disclosure.' An agent has enough context to call it correctly and interpret results properly.

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 full parameter documentation burden. It does so exceptionally: each parameter is listed with purpose, examples, and constraints (`limit <= 100`, `as_of` format, `tickers` as Chinese/English codes, `doc_type` examples). This goes well beyond the bare 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: 'Semantic search over MOPS filings, financial-statement notes and company news.' It immediately distinguishes itself from keyword filtering with concrete example questions, so an agent can tell it apart from sibling search-like 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 clear context: use `as_of` for backtest-shaped queries, and use `source_tier: 'official'` to exclude press. However, it does not name sibling alternatives or state explicit when-not-to-use conditions, 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?

The description adds substantial behavioral detail beyond annotations: the alert outlives the conversation, is evaluated against official daily closes, is delivered to the realtime stream and webhooks, and is signed, retried, and de-duplicated. It also explains that reusing rule_id updates rather than duplicates, which complements the idempotentHint annotation without contradicting it.

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 front-loaded with a one-sentence purpose, followed by a compact behavioral paragraph and a well-organized Args list. Every sentence adds operational value, with no filler or repetition of schema 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?

For a persistent, side-effecting notification tool with six parameters and no schema-level enums, the description covers purpose, persistence, delivery, idempotency, edge behavior, and every parameter's meaning. Since an output schema exists, omitting return-value details is appropriate.

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 input schema has 0% parameter description coverage, but the description fully compensates by explaining all six parameters: rule_id update semantics, symbol format with an example, direction allowed values, threshold units in TWD, label as optional, and edge_triggered exact firing behavior. This is essential given the schema provides only raw names and types.

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 clear verb and resource: 'Leave a standing instruction: tell me when this symbol crosses this price.' It also explicitly separates this from order/trade tools, making its purpose unambiguous and distinct from siblings like list_alerts and delete_alert.

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 clearly states this is for standing price-crossing notifications that outlive the conversation and explicitly warns 'This is a NOTIFICATION, not an order' and 'Nothing in TWMD can place a trade.' However, it does not explicitly name alternatives such as list_alerts or delete_alert, so it stops short of full alternative routing.

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?

Despite annotations already marking this as read-only and idempotent, the description adds substantial behavioral detail: the as_of gotcha for company_peer_groups (returns current grouping with pit_notes), the unbuilt source causing cannot_see entries with status=no_loader, and the does_not_prove flag. These behaviors are not visible in annotations and directly help an agent interpret results correctly.

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 bulleted structure is clean and front-loaded with the core resource definition, followed by warnings, arguments, return envelope, preconditions, and side effects. Each bullet adds distinct information, though the SIDE EFFECTS line duplicates the information already provided by the readOnlyHint annotation.

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 addresses the tool's key complexities and failure modes: the as_of behavior, unbuilt source loader, divergence detection via concerns, and the meaning of does_not_prove, cannot_see, and pit_notes. Combined with the output schema and annotations, an agent has enough to invoke it correctly. Minor gaps remain, such as ticker semantics and as_of format.

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 compensates only partially: it gives a ticker example ('2330') and notes as_of is optional. It also explains a subtle behavior of as_of regarding peer group timing. However, it does not explain what ticker represents or the expected date format for as_of, leaving partial ambiguity for both parameters.

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 resource (supply chain and peer data) and lists specific data dimensions: industry chain position, peer grouping, investments, and export orders vs revenue. It also states it is a fact compilation, not investment advice or prediction. However, it does not explicitly differentiate itself from sibling tools, so the distinction is implicit in the domain rather than named.

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 context about what to expect (not advice, honest envelope, missing source) and states a precondition (requires an identified session), but it never explicitly states when to choose this tool over alternatives. There are no exclusionary conditions or named sibling alternatives, so usage guidance remains implied by the tool's domain.

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 this as read-only and idempotent, and the description adds substantial behavioral context: paid datasets never have their row list consulted, rows_withheld reports what was held back, and withdrawn datasets remain refused regardless of sign-up. No contradiction with 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 longer than typical, but it is well-structured with bolded section headers and each section conveys a distinct behavioral fact. It front-loads the core purpose in the first sentence, and the extra length is mostly earned by explaining edge cases and exclusions.

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 read-only annotations, output schema, and the relatively simple parameter set, the description covers the necessary context: what is free, which tickers work, how paid datasets behave, how withheld rows are signaled, and when withdrawn datasets are unavailable. An agent has enough to decide when and how to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for explaining parameters, but it only lists the arg names at the end ('dataset, keyless_eligible, rows') and provides indirect context for keyless_eligible. It does not concretely define what the rows parameter accepts or how it controls the sample, leaving a meaningful gap.

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 object: 'Hand an unregistered caller a short taste of an open dataset, plus where to unlock the rest.' This makes the tool's function immediately recognizable and distinguishes it clearly from query_dataset by explicitly stating 'NOT `query_dataset`.'

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 explicit when-to-use guidance: for unregistered or planless callers who would otherwise receive a flat refusal, and only when someone hits the edge of their entitlement. It also names the alternative, query_dataset, and explains that query_dataset serves entitled callers in full.

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