MoveSurge

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new context beyond that: figures come from the database and are cached, and reaction_count_definition explains the historical counters. That provenance/caching detail is exactly the kind of addition that earns credit on top of 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 sentences, front-loaded with what the tool returns, then when to use it, then a data-provenance note. Nothing is padding, though the field enumeration overlaps somewhat with the output schema.

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

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

An output schema exists, so return values need no explanation here, and the description still covers purpose, usage intent, and data provenance/caching. For a zero-parameter, low-complexity tool, 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 tool takes zero parameters, so the baseline is 4 and there is no parameter syntax to document. The description does not invent or misdescribe inputs.

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

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

The description names a specific resource (coverage statistics for MoveSurge) and enumerates the exact figures returned: date range, total events, measured price reactions, distinct tickers, unbroken months. That is far more specific than a tautology. It does not explicitly contrast itself with any sibling tool, so it stops short of a 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?

It states concrete use cases — judging whether the source is worth citing, or stating its coverage accurately. There are no exclusions or named alternatives, but given the tool has no parameters and no overlapping sibling, the context is sufficient.

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/destructive=false, so the safety profile is covered. The description adds real content-level disclosure: which metrics are returned and the 'where measured' caveat that price reaction may be absent, which is useful behavioral context beyond the annotations and schema.

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

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

Two sentences, front-loaded with the returned payload before the usage examples, with no filler. The first sentence is dense but each clause carries distinct information, so it earns 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?

With 7 well-described optional params, an output schema, and annotations covering safety, the description only needs to convey scope and intent, which it does. Nothing critical to correct invocation is missing, though it could note pagination/limits behavior.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema. The description only implicitly touches parameters (the 'who reports next' clause corresponds to days_ahead) and adds no format or interaction detail, so the baseline 3 applies.

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

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

The description names a specific resource (reported earnings results) plus the exact payload: EPS and revenue vs consensus, beat/miss, guidance direction, price reaction, and the upcoming calendar. It is unmistakably distinct from macro siblings like economic_data, though it never names an alternative tool explicitly.

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 three concrete triggering questions ('did NVDA beat', 'how did the stock react to earnings', 'who reports this week'), which clearly maps the tool to intent. There is no explicit when-not guidance or pointer to a competing sibling, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description earns credit by disclosing the content shape (actual/forecast/previous, surprise direction, measured reaction in the minutes after release) and that results default to high-impact releases, with archive coverage disclosed via a parameter — substantive behavioral context beyond the annotations.

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

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

Two sentences, front-loaded with what the tool returns before the use cases. The parenthetical field list is dense but each element is informative; no filler sentences.

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

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

An output schema exists so return values need not be described, and annotations carry safety. The description covers the released-data plus forward-calendar duality and the high-impact default, leaving only minor gaps such as pagination/limits behavior, which the schema handles.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including the 'high' default for impact. The description's 'defaults to high-impact releases' largely restates the schema default, adding no syntax or format detail the agent doesn't already have; baseline 3 applies.

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

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

States a specific resource (released economic data: CPI, payrolls, PMIs, central-bank decisions) and the exact payload (actual vs forecast vs previous, surprise direction, market reaction), plus the upcoming calendar. This is clearly distinguishable from siblings like earnings or event_screen without opening any schema.

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

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

Gives two concrete usage exemplars ('what did CPI come in at and how did markets react', 'what data is out this week') that map to the released-data and calendar halves of the tool. It provides clear context for when to reach for it, but names no alternative sibling or exclusion 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: a bounded event sample rather than all stocks, returned headline links and actual numbers, and an explicit 'never trade recommendations' disclaimer. It stops short of describing sample size or latency.

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

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

Three sentences with no filler, and the primary screening purpose is front-loaded. The second sentence ('Or find published analysis of exposure for other companies (read-through), separately from price evidence') is syntactically tangled and could be tightened, but it does carry a real mode.

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 9 parameters, an output schema present, and 89% schema coverage, the description covers the important extras: scope bound (event sample, not all stocks), output content (numbers and headline links), and mode distinctions. It does not clarify that all parameters are optional or what a default call returns, but the output schema carries the return-value burden.

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 89%, well above the 80% threshold, so the schema already documents hours, limit, query, screen, timestamps and min_initial_move_pct. The description only adds 'supports ticker, topic and dates', which is a generic restatement. The baseline 3 applies since the schema does the heavy lifting.

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

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

The description names a specific verb and resource ('find news where an initial price move reversed, faded... or continued') and enumerates the four screening modes, which maps directly to the screen enum. It implicitly separates itself from pure price tools and headline search, but it never names a sibling like explained_moves or search_headlines to make the boundary explicit.

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?

'Or find published analysis of exposure for other companies (read-through), separately from price evidence' hints that read_through is a distinct mode from price screening, which is useful routing. However, there is no explicit statement of when to pick this tool over siblings such as explained_moves or search_headlines, and no prerequisites 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?

Annotations already establish read-only, non-destructive, non-open-world behavior, and the description adds a real disclosure beyond them: only moves with medium or high confidence are published, and the investigative pipeline is retrospective ('detected first and then investigated'). It does not mention coverage-universe limits, which matters given openWorldHint=false.

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 tight sentences: what it is, when to use it, and the publication threshold. The most decision-relevant information (the resource and its distinctive investigated-cause framing) is front-loaded with no 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?

With an output schema covering return values and annotations covering safety, the description supplies the remaining decision-critical context: confidence-gated publication and the investigative framing. The only gap is that it never states the asset/coverage universe the tool actually covers.

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

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

Schema description coverage is 100%, so all five parameters (asset, hours, limit, end_utc, start_utc) are already documented in the schema, including the end_utc override and the 72-hour default. The description adds no parameter-level meaning beyond that, so baseline 3 applies.

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

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

States a specific resource (abnormal price moves MoveSurge detected and investigated) plus the payload it returns (cause, evidence, confidence, follow-through). This cleanly separates it from raw-mover siblings like top_movers and narrative siblings like search_headlines.

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 concrete triggering question ('why did oil / the Nasdaq / a stock suddenly move') and a negative condition ('when no single headline explains it'), which implicitly routes headline-driven questions to search_headlines. It stops short of naming the alternative tool explicitly.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: results are Markdown and include sources and a measured reaction table, and the slugless mode returns a capped list of 25 recent articles.

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

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

Two tight sentences, no filler. The primary fetch behavior is front-loaded and the alternate listing mode follows immediately.

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

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

An output schema exists, so return-value structure need not be repeated, and the description still supplies the output format and content highlights. Both invocation modes are covered and no prerequisites or gotchas are left implicit.

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

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

Schema coverage is 100% and the schema already states that omitting slug lists recent articles. The description adds meaning by quantifying that list ('the 25 most recent articles') and implying the slug selects a specific article, which is slightly more than the schema provides.

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 ('Fetch') and resource ('a MoveSurge explanatory article') plus the output format (Markdown) and the notable contents (sources, measured reaction table). It also documents the second mode (listing with no slug), making it fully distinguishable from siblings like explained_moves or search_headlines.

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 clearly explains the conditional invocation: call with no slug to list the 25 most recent articles. There is no explicit when-not-to-use or named alternative, but the sibling set contains no competing article fetcher, so the context is 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description goes beyond them by disclosing the return contents and adding the interpretive caveat 'A price move alone does not prove the cause', which is genuinely useful context for an agent reasoning over results.

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

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

Four short sentences, front-loaded with the core verb/resource and return shape, with the caveat last. Dense and largely waste-free, though the matching-rule sentence partly duplicates the schema.

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

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

With an output schema present, the description needn't document return fields, yet it still summarizes them. All 8 parameters are optional and fully schema-documented, so an agent has enough to call it correctly; only cross-tool routing remains thin.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the AND-matching rule the schema already documents and only lightly adds that start_utc/end_utc can pin a specific date, without clarifying interaction with hours/before_hours or the impact enum.

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 ('Search real-time financial news by words or ticker') and even previews the return shape (dated headlines, links, pre/post prices). It does not explicitly distinguish itself from close siblings such as get_article or explained_moves, so it stops short of a 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?

It gives parameter-selection guidance ('Use start_utc/end_utc for a specific date') and matching semantics, which implies the search use case. However, it never says when to prefer this tool over explained_moves, event_screen, or get_article, so the routing guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without description help. The description's only added behavioral payload is that each event comes with a measured reaction, which is a modest but real disclosure about the returned data shape; limits, defaults, and window behavior are left to the schema.

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

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

Two short sentences, zero filler, with the resource and scope stated first and the use case second. Nothing could be removed without losing meaning.

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 annotations covering the safety profile, a 100%-documented input schema, and an output schema that carries return-value detail, the description only needs to convey purpose, scope, and use case — all of which it does. The remaining gap is sibling disambiguation against the other event/move tools, which is a usage-routing concern rather than a completeness failure.

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

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

Schema description coverage is 100% for all five parameters (days, limit, ticker, end_utc, start_utc), including ranges, defaults, and the fact that end_utc overrides the relative window. The description adds no parameter meaning beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource pair: recent tape events scoped to a single ticker, with the added detail that each event carries a 'measured reaction.' That is far more informative than the title alone, but it never distinguishes itself from close siblings such as explained_moves or event_screen, so the agent must still infer which of the overlapping history tools to pick.

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 sentence "Use to answer 'what has been driving <ticker> lately'" gives an explicit usage context, which is better than nothing. However, it names no alternatives and no when-not condition, and the sibling set (explained_moves, event_screen, top_movers) clearly overlaps with this scenario, leaving the routing decision implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the coverage cap of 400 newest eligible events, that results include per-sample time windows and quality notes, and that the scan reports its coverage limit — important caveats about data completeness for a ranking 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?

Three sentences, front-loaded with the core action and scope, with no filler. The final clause about the coverage limit is slightly redundant with the earlier 'newest 400 eligible events' statement, which keeps it just short of a 5.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description supplies the missing pieces an agent needs — the coverage cap, quality caveats, and the anti-scope warning — though it stops short of naming the alternative tools for full routing completeness.

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

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

Schema description coverage is 100%, so all five parameters (hours, limit, end_utc, start_utc, min_move_pct) are already documented with ranges and defaults. The description references a 'window' but adds no syntax, precedence, or interaction detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Rank price moves around news') plus a precise scope ('newest 400 eligible events in the window'). It distinguishes itself from a generic gainers/losers list, though it does not name the closest siblings such as explained_moves or coverage_stats, so an agent still has to infer routing among them.

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

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

Usage is only implied through the negative statement 'This is not a full-market daily gainers/losers list', which is not one of the sibling tools. There is no explicit when-to-use or 'use X instead' guidance relative to explained_moves, event_screen, or coverage_stats, so an agent gets partial but incomplete routing help.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral context: results are anchored to posts 'as they crossed the tape' with prices attached only where 'available', implying a joined dataset with possibly missing price fields rather than raw post text. It does not discuss update latency or pagination, which are the remaining gaps.

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

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

Two sentences, no filler. The capability statement comes first and the usage examples follow, so the reader gets the highest-value information up front.

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

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

An output schema exists, so return-value explanation is not needed, and the description covers what is fetched and when to use it. Minor omissions remain around data freshness/update cadence and how the relative look-back interacts with the UTC parameters, but nothing blocks correct invocation.

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

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

Schema description coverage is 100%, so all six parameters (hours, limit, query, end_utc, start_utc, with_reaction_only) are already documented in the schema with ranges and formats. The description only implicitly motivates with_reaction_only via 'available prices' and adds no new per-parameter meaning, so the baseline 3 applies.

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

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

States a specific resource (Truth Social posts by President Trump) plus the distinguishing payload (prices before and after the post). Nothing in the sibling list (search_headlines, get_article, explained_moves) covers this source, so an agent can route here from the name and first sentence alone.

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 two concrete triggering questions ('what has Trump posted today', 'did his tariff post move markets'), which makes the intended use unambiguous. It stops short of naming alternatives (e.g. search_headlines for broader news) or stating when this is the wrong tool, so it is strong context without explicit exclusions.

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