Stonkwatch

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds behavioral details: one-shot call, cost (5u), daily quota deduction, and conditions for sentiment score. No contradictions, but could mention error handling or response format.

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 plus a cost note. All information is front-loaded and no unnecessary words. Each sentence provides essential guidance (purpose, advantage, cost). Excellent use of space.

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 output schema, the description explains what is returned: coordination breakdown, interpretation, and optionally adjusted sentiment. It also covers cost and quota. Missing details like error handling or behavior when parameters are invalid, but overall sufficient for typical use.

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

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

With 0% schema description coverage, the description must compensate. It explains raw_sentiment's purpose and conditionally yields an adjusted score, and implies the use_case enum categories. However, it does not describe symbol, market, or rationale parameters, leaving gaps for an agent.

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 clearly states it's a one-shot decision tool that returns coordination breakdown, use-case-specific interpretation, and optionally a coordination-adjusted sentiment score. It distinguishes from sibling tools by name (get_coordination_breakdown) and explains the advantage over chaining.

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 recommends this tool over chaining get_coordination_breakdown with manual sentiment dampening, and mentions it matches the canonical filter_sentiment endpoint. Also provides cost and quota information, aiding agent decision.

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 indicate readOnlyHint=true, so the description adds value by detailing the cost model ('1u per call (~$0.01 via x402, deducts 1 from daily quota)') and mentions the return fields. 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?

Two sentences, clearly separated: first for purpose and outputs, second for cost. No redundant information, well front-loaded.

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

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

The tool has 5 parameters, no output schema, and is a financial calculation. The description lists outputs but does not specify their format or meaning. While the annotation provides readOnlyHint, more detail on parameter relationships (e.g., how marginal tax rate relates to taxable_income) would improve 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 coverage is only 20% (only 'rationale' has a description). The description does not explain inputs like 'cash_dividend', 'taxable_income', or 'franking_percentage', relying on implicit understanding. For a financial tool, this is insufficient for an agent to correctly invoke it.

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 explicitly states 'Calculate Australian franking (imputation) credits for dividends' and lists specific outputs, providing a clear verb+resource. It distinguishes itself from sibling tools like 'get_quote' or 'get_market_signals', which have different purposes.

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 mentions it is for Australian franking credits but does not provide explicit guidance on when to use it versus alternatives or when not to use it. No exclusions or prerequisites are 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 set destructiveHint=true, and the description explains the cost (1u per call, $0.01, quota deduction) and that the report is 'frozen in time,' adding behavioral context beyond annotations. 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 two short paragraphs: one for function, one for cost. It is front-loaded with the primary purpose. Every sentence adds value, though it could be slightly more structured (e.g., bullet points for parameters). Overall efficient.

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 6 parameters (including nested objects), no output schema, and only 17% schema coverage, the description fails to adequately explain input requirements and return format. Critical details like how to specify the content composition are missing, making it hard for an agent to use correctly without additional knowledge.

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 only 17% (only 'rationale' has a description). The description gives high-level hints about content ('stock snapshot, timeline, narrative') but does not explain the structure of the 'content' object, or the meaning of 'mode', 'market', 'window', or 'symbol'. This leaves the agent with insufficient guidance for constructing valid 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 specifies 'persist a composed stock-page report... as a stable shareable URL,' using a specific verb ('persist') and resource ('stock-page report'). It clearly distinguishes the tool from sibling data-fetching tools like get_stock and get_timeline by focusing on composition and sharing.

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 states the tool 'takes the tool outputs the caller already has,' implying it is used after collecting data from other tools. It mentions the URL output for sharing. However, it does not explicitly contrast with alternatives or specify when not to use, though the prerequisite is 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?

Annotations provide readOnlyHint=true and destructiveHint=false. The description adds value by disclosing the cost (1u per call, ~$0.01 via x402, deducts from daily quota), which is beyond what annotations offer.

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 (three sentences), front-loads the main purpose, and adds essential cost/scope details without unnecessary 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?

Without an output schema, the description details return fields (total calls, error rate, top tools, recent_calls ledger with sub-fields). It also covers cost and purpose. Minor omission: could mention ordering or limits.

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 description must compensate. It explains caller_id effectively and implies window_hours by 'last N hours', but does not describe the 'rationale' parameter, leaving a 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 states the tool returns the agent's own usage footprint, specifying fields like total calls, error rate, top tools, and a recent_calls ledger. It is specific but does not explicitly differentiate from sibling tools.

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

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

The description explains when to pass caller_id and mentions cost/reconciliation use cases, but lacks explicit guidance on when to use this tool versus alternatives among the 26 siblings.

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 indicate readOnlyHint=true and destructiveHint=false, so it's a safe read operation. The description adds valuable context about cost (1u per call, ~$0.01 via x402) and daily quota deduction, which are not in 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 brief (two sentences plus cost info) and the first sentence clearly states the purpose. It is front-loaded but could be slightly better structured for readability.

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 simplicity (one required parameter, no output schema), the description covers cost and quota but does not explain what the output looks like or any caveats. It is adequate but not fully 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?

With schema description coverage at 50% (only rationale has a description), the description does not add meaning for the announcement_id parameter. It merely states 'keyed by announcement_id' which is already implied by the 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 clearly states the tool provides an AI-generated summary of company filings/announcements, specifying content, key points, sentiment, and financial impact. It also mentions it corresponds to the AI-SUMMARY facet seen by humans, distinguishing it from other 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?

There is no explicit guidance on when to use this tool versus alternatives like get_sentiment or get_narrative. The description mentions cost and quota but does not help the user decide when this tool 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 declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds critical behavioral context: cost (1u per call, ~$0.01, deducts from daily quota), that the chart is a price snapshot at request time (not live), and that marker placement reflects created_at, not the spike's first observation. 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?

Two paragraphs, front-loaded with the most important details (output size, content, intended embed use), and every sentence adds value. No filler or repetition.

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 no output schema, the description fully explains the return value (SVG, size, chart elements, marker behavior). It also covers cost, usage context, and behavioral nuances. The tool is simple with few parameters, and the description covers all necessary aspects for an agent to invoke it correctly.

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

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

Schema description coverage is 50% (only rationale is described in schema). The description does not explain attribution_id beyond its name, though its purpose is somewhat implied by the tool name. The rationale parameter's description in the schema provides some guidance. Overall, the description adds limited semantic value beyond the 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 clearly states the tool returns an inline 1200x630 SVG price chart for a single attribution with a vertical marker at the attribution time and headline_citation text. It distinguishes from siblings like get_attribution_graph or get_attribution_timeline by specifying the chart type and intended use.

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 the tool is 'designed to be embedded by another agent in its own answer', providing clear context for when to use it. It does not explicitly mention when not to use it or direct alternatives, but the purpose is clear enough for an agent to infer appropriate use.

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 the tool is clearly safe. The description adds important behavioral context: the probabilistic nature of attribution, the meaning of evidence tiers, and a disclaimer about rumour-class signals not being confirmed causal. It also states the cost (1u per call), which aids agent decision-making.

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 reasonably concise, consisting of two sentences and a cost note. It is front-loaded with the core purpose. However, the first sentence could be slightly more structured (e.g., breaking down nodes and edges more clearly).

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 covers the main output elements and the probabilistic disclaimer, but lacks details on output format, pagination, or how evidence tier counts are represented. Given the complexity (graph data with multiple node/edge types), more completeness would be beneficial.

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 only 20% (only the rationale parameter has a description). The tool description does not explain the other four parameters (market, symbol, since_ts, min_evidence_tier). For an under-documented schema, the description fails to compensate, leaving parameter semantics unclear.

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

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

The description clearly states that the tool returns 'attribution graph nodes and edges for a ticker' and enumerates specific content (spikes, authors, announcements, edges). This differentiates it from siblings like 'get_attribution_chart' (which returns a chart) and 'get_attribution_timeline' (which returns a timeline).

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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. It only describes what the tool returns, leaving the agent to infer usage context.

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 discloses the cost (1u per call, ~$0.01, daily quota deduction) and the probabilistic nature of evidence tiers, adding significant value beyond the readOnlyHint and destructiveHint annotations. There is 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 four sentences, each serving a clear purpose: defining the tool, its use case, a caveat, and cost. It is well-structured and front-loaded with the core functionality.

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 output schema, the description provides a reasonable idea of return structure (score before/after, triggering signals). Parameter documentation is weak, but the tool is read-only with good annotations, and the purpose is clear for an agent to decide invocation. Minor gap in output format details.

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 only 33% (only rationale has a description). The description does not explain the adapter parameter or provide guidance on how to obtain attribution_id. While 'single attribution' implies attribution_id is key, the lack of detail leaves the agent with ambiguity.

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 tool as retrieving score-evolution history for a single attribution, specifying the verb 'get' and the resource 'attribution timeline'. It distinguishes itself from sibling tools like get_narrative and get_attribution_chart by focusing on per-revision score changes and triggering market signals.

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 states it is useful for narrating why scores moved as new evidence arrives, listing example signals (Polymarket odds, X chatter, etc.). It also cautions that evidence tiers are probabilistic and not ground truth. However, it does not explicitly compare to alternatives or specify when not to use.

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?

Description discloses key behavioral traits: reputation is time-decayed and probabilistic, attribution is not ground truth, and evidence tiers indicate confidence. This adds significant value beyond the readOnlyHint 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?

The description is concise and front-loaded with the core purpose. The cost note is extra but not excessive. A bit more structure could improve readability, but overall efficient.

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 explains the reputation metric and probabilistic nature fairly well. However, the absence of any output schema means the agent may not fully understand the returned 'backlinks' or overall structure.

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 only 25% (only 'rationale' has schema description). The main description does not clarify the meaning or usage of the other three parameters (handle, platform, symbol), leaving ambiguity.

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 'reputation scorecard and backlinks for a social author', with specific details on how reputation is computed (time-decayed direction_match rate). This distinguishes it from sibling tools like get_reputation_consensus or get_signals.

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?

No explicit guidance on when to use this tool versus alternatives. The optional 'rationale' parameter hints at pre-trade checks, but there is no clear when-to-use or when-not-to advice.

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 annotations (readOnlyHint=true, destructiveHint=false), the description adds behavioral context: cost of 5u per call, deduction from daily quota, and prerequisite of fetching a spec. It also clarifies the output format and interpretation pitfalls, providing complete transparency for a read-only operation.

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 and output, followed by essential usage instructions and cost details. Every sentence adds value, and the structure is logical and compact 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?

For a complex tool with 4 parameters and no output schema, the description covers purpose, output, prerequisite, cost, and common pitfalls. However, it lacks parameter descriptions and does not detail the return format beyond penalty and breakdown. The spec fetch advice somewhat compensates, but missing parameter semantics reduce 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?

With 0% schema coverage, the description does not explain individual parameter purposes. While 'symbol' is inferred as ticker, 'rationale', 'market', and 'use_case' are not defined. The manual understanding is there, but the agent lacks explicit parameter semantics to map inputs 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?

The description clearly states that the tool returns a coordination penalty (0..1) and per-signal breakdown for a ticker, distinguishing it from organic discussion analysis. It uses specific verbs ('Returns') and names the resource ('coordination breakdown'), making the purpose unambiguous.

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 tells when to use the tool (for detecting coordinated vs organic spikes) and provides critical usage guidance: fetch the spec resource before using, do not guess thresholds, and warns that misclassification occurs without the spec. It also mentions cost and daily quota, aiding proper 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 indicate read-only and non-destructive. The description adds important context: it is 'correlation/approximation only, never financial advice', includes cost (1u, ~$0.01, quota deduction), and emphasizes it's a single call. These details go 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?

Description is well-structured: purpose front-loaded, bullet-like list of outputs, disclaimer. Every sentence adds value, though cost info is partially redundant with schema annotations. Could be slightly more concise but overall efficient.

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 no output schema, the description lists all major output types (announcement, trades, sentiment, reputations, trace) and sets expectations (synthesis, not financial advice). For a complex tool, this provides adequate completeness for initial 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?

Schema coverage is only 25% and the description does not explain parameters beyond symbol (ticker). market, rationale, and lookback_days are undocumented in description, leaving the agent with insufficient guidance for correct usage.

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 it returns a 'full cross-source story for a ticker' with specific components (announcement, trades, sentiment, reputations, trace). This distinguishes it from siblings like get_quote, get_sentiment, and get_timeline which focus on individual aspects.

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 comprehensive synthesis but lacks explicit when-to-use or when-not-to-use guidance relative to alternatives. It mentions the tool provides unique synthesis, but does not state exclusions or recommend it over specific siblings.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: the cost of 1u per call and the specific logic of surfacing cases where retail chatter precedes announcements. This enhances transparency 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?

The description is extremely concise: two sentences plus a cost line, each sentence serving a distinct purpose. The front-loading efficiently communicates the tool's core function and value proposition.

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 no output schema, the description gives a clear idea of the returned data type (lead signals with platform attribution and lead time). It also includes cost information. However, it does not specify the exact output fields or pagination behavior, leaving minor ambiguity.

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 only 25% (only 'rationale' has a description). The tool description does not explain the meaning or usage of parameters like 'limit' or 'market', which are left to the schema types. For a tool with low schema coverage, the description should compensate but does not.

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

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

The description clearly states the tool returns 'pre-announcement social chatter for a ticker' and specifically surfaces cases where retail chatter preceded official announcements. It uses a specific verb ('get') and resource ('lead signals'), distinguishing it from the sibling 'get_signals' which is more general. However, it does not explicitly differentiate from siblings like 'get_market_signals'.

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 tool is for detecting lead signals before announcements, but it lacks explicit guidance on when to use this tool versus alternatives such as 'get_signals' or 'get_announcement_summary'. No when-not or recommended scenarios are provided.

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 significant behavioral context beyond the annotations (readOnlyHint, destructiveHint). It discloses the cost (5u per call), quota implications, data derivation from public order books, interpretation of confidence and volume, and warns against treating signals as ground truth. There is 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 concise, front-loaded with purpose, and each sentence adds value: purpose, output fields, usage context, data sources, caveats, and cost. No unnecessary words or repetition.

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 compensates for the lack of output schema by listing output fields and providing interpretation. However, it does not cover the limit or adapter parameters, which are important for tool usage. Overall, adequate but has clear gaps in parameter documentation.

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 only 25% (only rationale has a description). The description clarifies the ticker parameter by stating it's for a single ticker, but fails to explain limit (how many recent signals) or adapter (provider filter?). Thus, the description does not adequately compensate for the low schema coverage, leaving key parameters ambiguous.

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 retrieves 'recent prediction-market signals for a single ticker, sorted by most-recent first', specifying the verb (get), resource (prediction-market signals), and scope (single ticker). However, it does not explicitly differentiate from sibling tools like get_signals, which may have a broader 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 provides a direct use case: 'Use to answer 'what are prediction markets pricing for this ticker right now?''. It also includes context on data sources and caveats. However, it does not mention when to avoid using this tool or suggest alternatives among siblings.

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 readOnlyHint=true. The description adds important details: every sentence cites [sN] markers mapping to a sources array, orphan citations cause failure, and cost of 10u per call. This provides behavioral transparency 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?

Three concise sentences: first explains purpose, second adds output constraint, third gives cost. No wasted words, well front-loaded.

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 8 parameters and no output schema, the description lacks guidance on parameter usage and output format details. It covers cost and citation constraint but omits when to use different formats or lengths, making it incomplete for complex usage.

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 only 13% (only rationale has a description). The tool description does not explain parameters like format, market, window, max_length, or custom_prompt. It only implicitly references modes (trader, journalist, investor) which are already in the schema enums.

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 clearly states it performs persona-shaped LLM synthesis for a ticker, with three specific modes (trader, journalist, investor). It distinguishes from siblings like get_quote or get_sentiment, which provide raw data or analysis, by emphasizing synthesis and narrative generation.

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?

No explicit guidance on when to use this tool versus alternatives. The description implies it's for narrative synthesis, but does not mention when not to use it or compare to siblings like get_timeline or get_signals.

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 annotations (readOnlyHint: true, destructiveHint: false), the description adds critical behavioral details: ASX data source differences (Stonkwatch vs Yahoo Finance), cost and quota deduction, and the lack of social intelligence for non-ASX listings. 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?

Two concise sentences plus a list of supported markets and cost note. Every sentence provides essential information, no fluff. Front-loaded with the tool's core function.

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 covers key behavioral differences and cost but does not specify return format or error handling. Given no output schema, this is acceptable for a simple quote tool, but a mention of response structure would be beneficial.

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 significant meaning to the 'market' parameter by explaining its default value and data source implications. It does not add extra for 'symbol', but the schema already covers its type. 'Rationale' has schema description. Overall, enhances schema coverage from 33%.

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 it provides a 'market-aware price quote for a single symbol' with specific behavior for ASX vs other markets. It uses a specific verb (get) and resource (quote), and distinguishes itself from sibling tools like get_stock.

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 implicitly tells when to use the tool (when needing a price quote) and lists supported markets. However, it does not explicitly state when not to use it or compare to alternative tools for similar 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?

Description adds significant behavioral context beyond annotations: probabilistic nature of attribution, confidence classes (rumour/speculative as non-causal), and cost (1u per call, $0.01 via x402, daily quota deduction). No contradiction with readOnlyHint or destructiveHint.

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 paragraphs, front-loaded with purpose. Some slight redundancy ('Attribution is probabilistic' repeated), but overall efficient. Could be more structured with explicit parameter section.

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?

Describes return fields (canonical_url, headline_citation, evidence tier), cost, and probabilistic nature. Missing pagination details for limit/offset and no explanation of adapter parameter. Acceptable given simple list output, but gaps remain.

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 only 25% (only rationale has a description). The description does not elaborate on limit, offset, adapter, or rationale beyond what's in the schema. Without parameter descriptions, the agent cannot infer meaning for these fields.

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 it's a 'Firehose of the most recent spike attributions across all tickers', including joined evidence references and revision scores. This distinguishes it from sibling tools like get_attribution_chart or get_attribution_timeline which are more specific.

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

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

No explicit guidance on when to use this tool versus alternatives. The description does not mention when-not-to-use or provide context for choosing over siblings like get_attribution_chart or get_attribution_graph.

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 indicate read-only and non-destructive behavior. The description adds detail about how data is processed (reputation weighting, manipulator exclusion) and cost/quota implications, which goes beyond the annotations without contradicting them.

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

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

Two sentences plus a cost line. No wasted words. The most important information is front-loaded. Every sentence contributes to understanding.

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 no output schema, the description enumerates all key return fields (score, confidence, counts, comments with backlinks). It also explains cost and quota. This is sufficient for an agent to understand what to expect.

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 low (25%) with only 'rationale' described. The description compensates somewhat by listing window options and default (24h|7d|30d, default 7d), but does not explain 'market' or 'ticker' beyond their presence. The return value list helps infer parameter purpose, but more parameter-specific guidance would improve usability.

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 provides per-ticker directional consensus weighted by reputation. It specifies what is returned and mentions unique features like manipulator exclusion. However, it does not explicitly differentiate from sibling tools like get_sentiment or get_signals.

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?

No guidance on when to use this tool versus alternatives. The description focuses on what it does and cost, but omits context such as when to prefer this over other sentiment or signal tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds cost info and output fields but no additional behavioral traits beyond what annotations imply.

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 and front-loaded with purpose. Cost line is extra but not wasteful. Could be more concise without losing clarity.

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 5 parameters and no output schema, the description provides minimal parameter details and returns summary. Lacks full context for an agent to use it without schema inspection.

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?

Only 20% of parameters have schema descriptions. Description mentions 'ticker' and 'timeframe' but does not explain market, timeframe values, or include_external beyond the 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 it aggregates social sentiment for a ticker over a timeframe, listing output fields. However, it does not directly distinguish from sibling tools like get_signals.

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?

No guidance on when to use this tool versus alternatives. Includes cost but not context for decision-making.

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 indicate read-only and non-destructive behavior. The description adds cost information (1u per call, quota impact) and clarifies it returns raw data, but does not disclose pagination behavior or rate limits beyond the cost.

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?

Extremely concise: two sentences plus a cost line. Front-loaded with core functionality, then usage context. 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?

High parameter count (13), no output schema, and low schema coverage demand a richer description. Missing details on pagination (cursor), date range, market filtering, and return format. Incomplete for effective agent decision-making.

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 only 8% schema description coverage, the description must compensate. It mentions filters (platform, verified, engagement, sentiment confidence) which map to a few parameters, but leaves many (cursor, since, until, limit, market, sort) undocumented. Partial coverage is insufficient for a 13-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?

Clearly states the tool retrieves raw social posts for a ticker with filters, distinguishing it as a 'breadcrumb endpoint' for journalists/traders and explicitly noting it's 'not the synthesised view'. This differentiates it from nearby siblings like get_market_signals or get_lead_signals.

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 context ('breadcrumb endpoint' for raw data) and implies it's for preliminary analysis, but does not explicitly state when NOT to use or compare to sibling tools. Leaves the agent to infer 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?

The description adds important behavioral context beyond annotations: it explains that attribution is probabilistic, that evidence tiers indicate confidence (e.g., rumour-class signals are not confirmed), and discloses cost (1u per call, daily quota impact). Annotations already indicate readOnlyHint=true, so 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 description is concise: two main sentences plus a cost line. It front-loads the core purpose. No redundancy, but could be slightly more structured (e.g., separating output from behavioral notes).

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 detail retrieval tool with no output schema, the description adequately covers output contents and data nature (probabilistic). It lacks explicit mention of error cases or pagination, but for this tool's simplicity, it is reasonably 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?

With schema coverage at 50%, the description does not elaborate on the parameters. The schema already describes rationale, but spike_id lacks description in the schema and is not explained in the description. The description focuses on output rather than parameter meaning.

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 it provides full detail for a single social spike, listing specific output components: contributing posts with author, platform, sentiment; attribution rows with lead time and evidence tier. This distinguishes it from siblings like get_attribution_chart or get_timeline which focus on specific aspects.

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 does not specify when to use this tool versus alternatives. It mentions cost and quota but lacks guidance on use cases or when not to use it. No explicit exclusions or comparisons to sibling tools are provided.

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 and destructiveHint, so the read-only nature is clear. The description adds cost details (1u per call, daily quota deduction) and notes that mode changes defaults only, providing extra behavioral context 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 only two sentences plus a cost line, with the core purpose front-loaded. Every sentence adds key information without repetition 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?

Given 6 parameters and no output schema, the description is insufficient. It does not explain output structure, valid values for the include array, or how mode affects defaults. An agent would lack critical information to use 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 coverage is only 17%; only the rationale parameter has a description. The description mentions the 'include' array and lists slice options but does not explain other parameters like mode, window, or signals_limit. The description provides some high-level meaning but fails to compensate for the gap in parameter 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 clearly states the tool retrieves a composite stock snapshot with specific slices (price, sentiment, etc.). The title 'Get Stock' is generic but the description provides a specific verb-resource and distinguishes it from siblings by listing the available slices.

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 tool is used when multiple slices are needed in one call, but does not explicitly state when to use it vs alternatives like get_quote or get_sentiment. No exclusions or scenario-based guidance is provided.

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 behavioral details: it merges multiple event types, computes lead/lag, and states cost (1u per call). It does not contradict 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 exceedingly concise: two sentences plus cost info. It front-loads the core purpose and avoids unnecessary elaboration. Every sentence adds value.

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

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

Despite the tool's complexity (10 parameters, no output schema), the description omits details about return format, pagination, ordering, or how parameters like since/until affect results. It is insufficient for an agent to fully understand invocation behavior without external knowledge.

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 only 10%, the description should compensate by explaining key parameters. However, it does not mention any parameter (e.g., mode, types, min_importance) beyond the schema's minimal information for 'rationale'. The agent must infer semantics from the tool name and overall purpose.

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's purpose: 'Merged time-ordered events for a ticker: announcements, social signals, and sentiment shifts in one stream.' It also specifies a distinct analytical angle ('answers did retail know first') that differentiates it from siblings like get_signals or get_attribution_timeline.

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 a use case (comparing social chatter to official filings) but does not provide explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or prerequisites, leaving the agent to infer usage context.

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 as read-only and non-destructive. The description adds important behavioral context about cost (1u per call, ~$0.01 via x402, deducts from daily quota), which is beyond annotations and helps the agent understand resource implications.

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

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

The description is extremely concise with two sentences, each serving a distinct purpose: purpose and cost. No extraneous text, front-loads the core functionality.

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 5 parameters (none required), no output schema, and many siblings, the description is insufficient. It does not describe the return format, how parameters affect results, or how to filter effectively. The cost info is helpful but not enough for complete agent understanding.

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 only 20% schema description coverage (only 'rationale' has a description), the description fails to explain the meaning of mode, limit, market, or window parameters. The description's brief mention of 'rank ASX stocks' does not clarify 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?

The description clearly states the tool ranks ASX stocks by membrane-potential activity score, using a specific verb ('rank') and resource ('ASX stocks'). This distinguishes it from siblings like get_quote or get_signals, which serve different functions.

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 calls this a 'Discovery entry point' but provides no explicit guidance on when to use it versus alternatives like get_signals or get_quote. There is no mention of prerequisites 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 indicate readOnlyHint=true, so the description adds value by disclosing the cost (1u per call, deductible from daily quota) and the nuance that ASX data comes from Stonkwatch's tracked data with social intelligence while other exchanges return live Yahoo Finance quotes without social intelligence. It also notes that adding a market is a registry entry, clarifying that the list is authoritative. No contradictions 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 with two focused paragraphs. The first paragraph delivers the core purpose and key details, while the second covers cost. No redundant or irrelevant information. Could potentially integrate cost into the first paragraph, but current structure is effective.

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 fully explains the return value (exchange metadata fields), the behavioral nuance (ASX vs other exchanges), cost, and the authoritative nature of the list. No output schema exists, so the description carries the full burden, and it succeeds admirably. All necessary context for an agent to understand the tool's output and usage implications is provided.

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 parameter 'rationale' is described in the schema. The description does not add any additional meaning or usage guidance for this parameter, so it merely meets the baseline expectation without exceeding it.

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

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

The description clearly states the verb 'list' and resource 'markets', specifies the metadata returned (code, display name, country, etc.), and establishes this list as the source of truth for cross-market coverage. It distinguishes from siblings by referencing get_quote's `market` argument and the difference in data source (ASX vs other exchanges).

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 the market code should be used as get_quote's `market` argument, providing clear context for use. It also explains the behavioral difference between ASX (full social intelligence) and other exchanges. However, it does not explicitly state when not to use this tool, though that is largely implied by its role as the reference for available markets.

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 indicate destructiveHint=true, which matches the description's mutating nature (purchase, cost deduction). The description adds context like cost and quota impact, which is beyond what annotations provide. No contradiction found.

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 plus a cost line, front-loaded with purpose. Every sentence adds necessary information with no waste.

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 2 params and no output schema, the description covers purpose, cost, and follow-up action. It could mention return value or confirmation, but it's nearly 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 coverage is 100%, so baseline is 3. The description adds an example for product but no extra meaning beyond schema. It mentions cost but not further parameter details.

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's purpose: to purchase access to a dataset, granting API key pulls. It uses a specific verb (purchase) and resource (dataset access), and the follow-on fetch step distinguishes it from siblings like export_report.

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 when to use (to buy dataset access) and includes cost details and the next API call. It lacks explicit when-not-to-use or alternatives, but the cost and quota mention provide clear context.

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 indicate read-only and non-destructive behavior. The description adds valuable behavioral context: cost per call (1u, ~$0.01), daily quota deduction, and that it 'resolves' to a canonical entity. No contradictions 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 extremely concise: two sentences. The first sentence states the core purpose, and the second provides crucial cost information. No redundant phrases.

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 annotations and cost info, the description lacks details on expected output format, error behavior (e.g., no match), and parameter usage. Given 5 parameters and no output schema, agents need more context to use the tool effectively.

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 only 20% schema description coverage (only 'rationale' has a description), the description should compensate by explaining parameters like 'type', 'limit', 'market', and 'query'. It does not; it only mentions 'query' implicitly. This leaves agents without enough context to fill parameters 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?

The description clearly states the tool resolves a query to a canonical ticker entity and positions it as the entry point for all session workflows, distinguishing it from sibling tools that are primarily data retrieval operations.

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 it is the first tool to call by stating 'entry point for all session workflows', but it does not explicitly specify when to use alternatives or provide exclusions. Cost information hints at usage restrictions but no direct 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 indicate destructiveHint=true (modifying state) and readOnlyHint=false. The description adds cost details (1u per call, deducts from daily quota) and mentions that feedback is mined to improve tools, implying persistence. 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 brief and front-loaded with purpose. Each sentence adds value. However, it could be slightly more structured (e.g., separating usage guidelines from cost info).

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 covers the tool's high-level purpose and when to use it, and mentions cost. However, it does not explain return values (no output schema) or parameter semantics (6 parameters, 0% coverage). For a feedback tool with required parameters, more detail is needed for agents to invoke it correctly.

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

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

Schema description coverage is 0%, meaning the description does not explain any parameter individually. While the description advises to 'include what you were trying to do', it does not map this to specific parameters like attempted_action or blocker. The agent lacks guidance on how to populate each field 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?

The description clearly states the tool's purpose: to submit feedback when a tool fails, with specific use cases (blocked, wrong shape, missing parameter, ambiguous docs). It distinguishes itself from sibling tools, which are mostly data retrieval tools (get_*).

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 tells when to call it (blocked, wrong response shape, missing parameter, ambiguous docs) and what to include (what was attempted). Provides clear context for usage, though it does not explicitly state 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.