StockMap

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

Goes beyond the readOnly/idempotent annotations by disclosing the data source (CoinGecko), that nothing is stored, and that the answer must carry a timestamp, sources, and a not-advice line. These are behavioral facts the annotations cannot express. No permission or rate-limit details, but the safety profile is already covered by 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?

Short overall and front-loaded with the core question and computation. The opening sentence is long and clause-chained, and the final sentence is a display instruction rather than tool semantics, but there is 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 present, the description needn't explain return shape, and it still usefully mandates surfacing the price stamp, sources, and disclaimer. Data source, storage behavior, and input format are all covered. Missing only comparative routing against sibling tools.

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

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

Schema description coverage is 100% and the schema already explains both `holdings` (paste string with optional date) and `since` (fallback date for undated holdings). The description repeats the same example paste string rather than adding syntax rules or edge-case behavior. Baseline 3 is appropriate 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?

States a concrete computation: price pasted holdings then and now against the same dollars held in Bitcoin, using CoinGecko prices. This is clearly distinct from siblings like compare_stocks or crypto_today, though the sibling differentiation is implicit rather than stated. The core purpose sentence is weighted down by clause-heavy phrasing but remains identifiable.

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 paste format ('ETH 2, SOL 40 since Jan 15') implies the input scenario, and 'Market data with no call on any coin' implicitly excludes advice-seeking use. However, there is no explicit when-to-use / when-not-to-use or named alternative (e.g., crypto_today for current prices, compare_stocks for equities), so routing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered; the description adds real value by disclosing the freshness model ('nightly') and imposing an output obligation (show the not-advice line and run date). It doesn't say whether the 2-5 range is hard-enforced at call time or what happens for unknown symbols, which are the remaining behavioral 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 with no waste: the first front-loads what the tool returns, the second covers when to invoke it and the compliance requirement. Nothing is repeated and the routing rule comes before the display instruction.

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

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

Output schema exists, so return shape needn't be spelled out, and annotations already carry the safety profile. The description still supplies the two things structured fields can't: the invocation trigger and the mandatory not-advice/run-date disclosure, leaving nothing an agent needs missing.

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

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

Schema coverage is 100% and the single 'stocks' parameter already documents symbol-or-company-name format and the 2-5 bound, so the description's 'by symbol or company name' and 'two to five' merely restate structured data. Baseline 3 applies since the schema carries the parameter semantics.

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?

Names a specific verb and resource ('StockMap's calls on two to five US stocks side by side') and enumerates the payload an agent gets back: nightly 14-day call, whether it changed, insights for/against, and past-call performance. The 2-5 stock range implicitly separates it from the single-stock sibling stock_call, though no sibling is named 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?

Gives explicit user-intent triggers ('how two to five US stocks stack up', 'which of them looks stronger') and even covers the case where the user doesn't mention StockMap, which is a meaningful routing rule. It stops short of stating when NOT to use it or naming the alternative tool for single-stock or non-US queries.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered by structured data. The description adds real context beyond that: it previews the exact composition of the answer (three rating buckets, graded-window accuracy, BTC move) and imposes a disclosure obligation (stamp, sources, not-advice line), signalling that the output carries provenance and a disclaimer. It does not contradict any annotation.

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, with the subject front-loaded ('Which US crypto stocks StockMap's model leans on'). The first sentence is a dense run-on stacking four clauses, which costs some clarity, but every clause carries content the agent cannot get from the schema or annotations.

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

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

With zero parameters, a rich annotation set and an output schema present, the description need not document return fields — yet it does sketch them, which is a bonus. Safety, scope and disclosure expectations are all covered. The one soft spot is that 'the stamp' is never defined, so the agent must consult the output schema to know what to display.

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 per the baseline this sits at 4. The description adds no parameter information and needs none; there is nothing for it to disambiguate.

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 (US crypto-exposed stocks scored by StockMap's model), a specific payload (outperform/neutral/underperform counts, hit rate on graded two-week windows, Bitcoin's move since last close), and explicitly scopes it against coin-focused siblings with 'The calls are the stock model's, on the stocks, never on coins.' It is clear on what it does, though the run-on phrasing makes the core verb harder to extract than it should be.

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

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

Usage is implied rather than stated: an agent can infer this is for a model's crypto-stock outlook, and the 'never on coins' line implicitly routes coin questions to bitcoin_test/crypto_today. However, no sibling is named as an alternative and there is no explicit when-to-use or when-not-to-use condition. The only explicit directive is presentational ('Show the stamp, the sources and the not-advice line'), which is useful but is output handling, not tool selection.

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 readOnly/idempotent/non-destructive/closed-world, so the bar is lower, and the description still adds real behavior: every number is sourced, the response includes a stamp and a not-advice line, and it makes no directional call. That is genuine output-contract context beyond the annotations, though it does not cover freshness or caching.

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 content enumeration is front-loaded in the first clause and the closing sentence is an actionable directive. It is dense but each clause carries information; the 'every number with its source' phrase is slightly redundant with the later mention of sources.

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 rich annotations, no parameters, and an output schema that documents returns, the description supplies the missing framing — what the page contains and the attribution/not-advice obligation on the answer. Only the freshness window of 'today' is 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?

The tool takes zero parameters, so per the baseline rule the schema carries the full burden and the description need not add parameter detail. Nothing here misleads about 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?

Names a specific resource and enumerates its contents: Bitcoin's 24-hour move, how many coins beat it, funding, and the hour's paragraph. An agent can tell it retrieves a daily crypto market explanation, not raw prices. It does not explicitly name a sibling, though 'no call on any coin' implicitly separates it from stock_call-type tools.

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

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

Usage is implied by 'Why crypto is up or down today' — the agent infers this answers a daily-move question — and 'Market data with no call on any coin' signals it is not a recommendation tool. There is no explicit when-to-use, when-not-to-use, or named alternative among bitcoin_test, crypto_stocks, or is_it_altseason.

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 readOnly, idempotent, non-destructive and closed-world, so the bar is lower. The description adds real value beyond them: the upstream source, an explicit no-recommendation stance, and a mandatory attribution/not-advice disclosure the agent must surface with the answer. It doesn't cover freshness or caching of the market data.

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 that lead with the computed metric before the sourcing and disclosure requirements. Dense but every clause carries information; the parenthetical '(stablecoins out)' and the attribution sentence both earn their 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?

With no parameters, an output schema present, and rich annotations, the remaining burden is explaining the metric definition and the required disclosure, both of which are covered. Missing only data freshness/timing, which matters for a 'last 7 days' market statistic.

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. The description confirms the fixed scope (top-100, stablecoins excluded, 7-day window) rather than leaving the implicit 'no options' framing unexplained.

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?

It states precisely what the tool computes: the share of top-100 non-stablecoin coins that beat Bitcoin over 7 days versus a typical-week baseline, sourced from StockMap's Altseason page. The metric is unambiguous and far more specific than the title alone. It doesn't explicitly contrast with near-neighbours like crypto_today, which keeps it off 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?

There is no statement of when to reach for this tool versus siblings such as crypto_today or market_map; the use case is only implied by the question-shaped name. The only directives given ('no call on any coin', 'show the stamp, the sources and the not-advice line') are output/attribution rules, not invocation 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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description is free to add real context: the grading lookback (calls made 14 days earlier), the inclusion of the next run start time, and the mandatory not-advice line and run date. That is meaningful behavioral disclosure beyond structured fields, with no contradictions.

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?

It is front-loaded with the purpose, but the whole definition is a single run-on sentence packing four distinct output elements plus a trailing formatting instruction ('Show the not-advice line and the run date with the answer'). Every clause carries content, yet the lack of structure makes it harder to scan than a short bulleted enumeration would be.

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

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

With an output schema present and annotations covering safety, the description's job is to set expectations about content and it does so thoroughly, including report timing. Only the relationship to sibling tools is left unaddressed.

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; there is nothing for the description to disambiguate. It correctly avoids wasting words on nonexistent 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 enumerates the concrete content of the report (band changes on the market map, the biggest movers, calls graded last night, next run start), so an agent can tell it produces a daily recap rather than a lookup. However, it never names or contrasts the neighbouring tools it overlaps with conceptually (market_map, stock_call), leaving the boundary to be inferred.

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 by the temporal framing ('what changed ... last night'), which suggests a once-a-day recap. There is no explicit when-to-use, when-not-to-use, or alternative named, and no statement such as 'use market_map for current bands' to route the agent.

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, non-destructive, closed-world behavior. Beyond that, the description discloses meaningful traits: it is a summary rather than per-stock data, leans come from the model's nightly calls (data recency), and every answer must carry the not-advice line and run date. Return shape is left to the output schema, which is reasonable.

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 map contains, then when to use it, then the output requirement. The dense first sentence is justified because each clause names a distinct data element the agent will surface to users.

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 explain return values, and it covers the remaining gaps an agent would face: what's included vs excluded (summary, not every stock), when to invoke, and the disclaimer/run-date requirement. Nothing essential is missing for a zero-parameter read 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 tool takes zero parameters, so the baseline is 4. Nothing in the input schema needs elaboration, and the description correctly focuses on scope and output conventions instead of inventing 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 states a specific resource and scope: a US market map of the 11 sectors with share, 2-week lean, daily move, and best/worst stock, plus 'A summary, not every stock.' This distinguishes it from siblings like sector (single sector) and compare_stocks without needing to open the schema.

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

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

It gives explicit trigger conditions — 'when someone asks how the US market looks, or which sectors lead or lag, whether or not they name StockMap' — and a required output convention (show the not-advice line and run date). It doesn't name a concrete alternative tool for narrower askers, so it falls short of a full 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds value beyond that with ordering semantics ('the calls that changed last night first') and a mandatory presentation contract ('Show the not-advice line and the run date'), which is real behavioral context the annotations don't carry.

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, both front-loaded: the first establishes scope and ordering, the second states the display requirement. No filler, no restatement of the title, and the most decision-relevant information comes first.

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 doesn't need to enumerate return fields, and it covers scope, ordering, and the required disclaimer/run-date presentation. The only gap is edge behavior (e.g., what is returned when the user has no watchlists) and any auth precondition, which are not addressed.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly spends no words on inputs and instead describes output shape.

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 framing ('The signed-in person's StockMap watchlists') and enumerates what each entry contains: stocks plus the model's call on each. It implicitly separates itself from siblings like `watch`/`unwatch` by scoping to reading the signed-in user's existing lists, though it never names an alternative 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?

Usage is implied by the possessive scope ('the signed-in person's'), making clear it's the read path for one's own watchlists. But there is no explicit when-to-use or when-not guidance, and no pointer to `watch`/`unwatch` for modification or `last_night` for pure change feeds, leaving the agent to infer 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?

Annotations already cover the read-only, idempotent, non-destructive, closed-world nature. The description adds valuable behavioral context: it explains what the output includes ('2-week lean from the model's nightly calls', 'how its stocks' calls split', etc.) and mandates showing the not-advice line and run date. It does not mention rate limits or auth, but given the annotation coverage, this is sufficient.

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

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

Two sentences, front-loaded with the core purpose, then usage and output instructions. The first sentence is dense but each clause adds relevant detail. No filler, though it could be slightly more 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?

Given the output schema exists, the description needn't explain return values, yet it usefully summarizes output content. Annotations cover safety, and the description fills in purpose, usage, and output display requirements. Nothing essential for correct invocation 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?

With 100% schema description coverage, the schema already documents the single 'name' parameter with examples. The description provides similar examples ('Information Technology, semiconductors, banks') but adds no new semantics like format or constraints beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('StockMap's read') and resource ('one US sector or industry'), and details the exact content returned (2-week lean, call splits, industries, largest stocks). It clearly distinguishes itself from sibling tools by focusing on sector/industry-level analysis rather than individual stocks or crypto.

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 when to use: 'when someone asks how a US sector or industry looks, or which of its stocks look strong or weak, whether or not they name StockMap.' It also instructs to show the not-advice line and run date. No alternatives are named, but the usage context is clear and complete.

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, closed-world, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the call is a nightly model output with a 14-day horizon, it includes the model's own historical performance, and the answer must carry the not-advice line and run date — operational obligations not visible in any structured field.

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 resource and its contents, then the usage trigger, then the display obligations — a logical ordering with no filler. The opening sentence is long and comma-heavy, carrying several payload items, but every clause conveys information an agent would otherwise have to guess.

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 no explanation; the description still previews the payload shape so the agent knows what to surface. Input, behavioral obligations, and disclaimers are all covered, leaving nothing essential for a 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% and the single parameter already documents both symbol and company-name forms with examples (NVDA, BRK.B / Nvidia). The description's "by symbol or company name" restates that without adding format, ambiguity, or ticker-resolution guidance, so it sits at the baseline for full schema coverage.

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 ("StockMap's call on one US stock") and enumerates exactly what the payload contains: 14-day call, bull/bear reasons, track record, price and day's change, and what changed overnight. That content list clearly separates it from siblings like compare_stocks, sector, market_map, or last_night, which cover different scopes.

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

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

Gives concrete triggering conditions — asking how a US stock looks, whether it is strong or weak right now, or what to make of it — and explicitly resolves the ambiguity of whether the user names StockMap. It stops short of naming an alternative sibling (e.g. compare_stocks for multiple tickers), so the routing signal is clear but not exhaustive.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds ownership scope ('signed-in person's watchlists') but does not clarify whether removal applies to all watchlists, what happens if the stock is not watched, or any auth/permission requirements.

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?

A single well-formed sentence with zero waste, front-loading the action and target.

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

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

Given a complete output schema, rich annotations, and a fully documented single parameter, the description is nearly sufficient. It states the target scope but leaves minor ambiguity about whether removal applies across all watchlists or a specific one.

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 single `stock` parameter is fully described in the schema with symbol/company-name examples. The description adds only the 'US stock' constraint, which is already reflected in the schema description.

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 (Remove) and resource (US stock from the signed-in person's StockMap watchlists), making the action clear. It implicitly contrasts with the sibling `watch` tool but does not explicitly name or distinguish from it.

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 no explicit guidance on when to use this tool versus alternatives such as `watch` or `my_watchlists`. Usage is only implied by the verb 'Remove'.

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 mutation, idempotency, and non-destructiveness, and the description adds critical behavior beyond them: a named list is created if absent, and a stock belongs to one list at a time so naming another list moves it. This is exactly the kind of side-effect disclosure an agent needs for a mutation 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?

Two sentences, front-loaded with the action and default behavior, then the key invariant. Every clause carries useful information with no wasted words.

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

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

For a two-parameter mutation tool with annotations and an output schema, the description covers the essential behavioral details: who the watchlist belongs to, default list selection, list creation, and move semantics. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by explaining the consequence of naming another list—that the stock moves rather than being duplicated—which clarifies the watchlist parameter's semantics.

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—adding a US stock to a watchlist—and immediately defines the scope as the signed-in person's StockMap. The move semantics and auto-creation of a named list make it unmistakably distinct from siblings like unwatch and my_watchlists.

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 situational context: use this to add a stock, optionally naming a list, with the default being the first list. It does not explicitly name alternatives or say when-not to use it, which keeps it 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.