Norges Bank

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already convey safety. The description adds value beyond annotations by specifying the default model, the need for an API key for Anthropic, and the return structure. 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, consisting of three sentences that efficiently convey purpose, models, return format, and use cases. It is well-structured with no redundancy, earning every sentence its place.

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

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

Given the tool's complexity (4 params, no output schema), the description covers essential aspects: purpose, parameters, return structure, and use cases. It lacks details on scoring methodology or rate limits, but for a read-only tool with strong annotations, it is sufficiently 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 meaningful context: it explains the relationship between the 'models' array and '_apiKey', clarifies default behavior, and elaborates on 'context' for disambiguation. This extra information justifies a slightly higher score.

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: probing LLMs for knowledge about an entity and scoring visibility (0-100). It specifies the verb 'probe', the resource 'LLMs', and includes a scoring range. It also distinguishes from siblings by detailing use cases like AI-marketing audits and pre-launch brand checks, which are unique among 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 provides clear context on when to use the tool, listing specific use cases. It explains the default model and the optional Anthropic probe with BYO API key. However, it lacks explicit 'when-not' guidance or direct comparisons to sibling tools like 'scan_competitor_ai_presence', which might overlap.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: it routes questions to the appropriate tool among 2,902, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This goes beyond the annotations to explain the internal routing and citation behavior.

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

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

The description is front-loaded with the key advice ('PREFER OVER WEB SEARCH'), followed by clear domain enumeration and examples. While somewhat lengthy, every sentence adds value. Minor conciseness improvements could be made, but it is well-structured for an agent to quickly grasp essential information.

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

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

For a single-parameter tool with rich annotations and no output schema, the description is comprehensive. It explains the tool's scope (2,902 tools, 633 sources), the expected output (structured answer with citations), and provides usage examples. There are no gaps that would prevent correct selection or 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 coverage is 100% with a single 'question' parameter described as 'Your question or request in natural language'. The description does not add new parameter-level detail beyond the schema's example values. Baseline 3 is appropriate since the schema fully documents the parameter.

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

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

The description clearly states the tool's purpose: to answer factual questions about current or historical data from 2,902 tools across 633 sources, with structured citations. It explicitly says 'PREFER OVER WEB SEARCH' and lists specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools like entity_profile or validate_claim.

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

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

The description provides explicit guidance on when to use this tool: for factual queries about real-world entities, events, or numbers, including specific trigger phrases like 'what is', 'look up', 'find', etc. It also gives concrete examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K'), leaving no ambiguity about appropriate use cases.

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 (readOnlyHint, openWorldHint, idempotentHint) are consistent and the description adds extensive behavioral context: fan-out logic, classifiers, response shapes, safety mechanisms, and edge case handling. This goes well beyond what annotations provide.

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

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

The description is well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY). It front-loads the core purpose. While lengthy, every sentence serves a purpose; no redundancy. The format aids readability for an AI agent.

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

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

For a tool with 3 parameters and no output schema, the description covers input handling, process flow, output structure, and edge cases comprehensively. It includes examples, classifiers, fan-out details, and safety notes, leaving no significant gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the market input formats, depth options (quick vs thorough), and include_raw tradeoffs. It does not repeat schema descriptions but enriches them with practical examples and explanations.

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 researches a Polymarket bet, specifying input types (slug, URL, question text). It provides the verb 'Research' and resource 'Polymarket bet', and the overall purpose is unambiguous. While not explicitly contrasting with siblings, the level of detail makes the tool's role distinct.

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 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides clear use cases but does not explicitly state when not to use or compare to sibling tools. However, it does include conditions that short-circuit (low confidence, closed markets, wide spreads), which serve as usage boundaries.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds significant context: data sources (SEC EDGAR/XBRL, FAERS, FDA), a fix for off-calendar fiscal years, result sorting, and citation URIs. 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?

Description is somewhat lengthy but every sentence provides value. It is well-organized: starts with purpose, use cases, then details per type, then result format and efficiency. Could be slightly more concise, but not overly verbose.

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

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

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description is remarkably complete. It explains what each type returns, sorting behavior, and provides context for the data fix. No gaps identified.

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% with descriptions for both parameters. The description enhances this by specifying that type='company' pulls revenue, net income, cash, long-term debt; type='drug' pulls adverse events, FDA approvals, active trials. It clarifies format for values (tickers/CIKs for company, names for drug).

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 compares 2-5 companies or drugs side by side, with specific verbs ('compare', 'rank-by-metric') and resource identification ('companies', 'drugs'). It distinguishes from siblings like entity_profile by focusing on multi-entity comparison.

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

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

Explicitly says when to use (comparison queries like 'compare X and Y', 'X vs Y', 'which is bigger', rank-by-metric) and notes it replaces 8-15 sequential lookups, implying not to use individual calls. Does not explicitly state when not to use, but context 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 already mark it read-only, idempotent, non-destructive. The description adds that it returns top-N tools with full schemas and curated examples, ready to call directly. This is useful but not rich behavioral detail beyond what annotations convey. 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 efficient sentences. The first front-loads the primary purpose; the second provides usage guidance and return details. Every part earns its place with no redundancy or fluff.

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

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

Given the tool's simplicity (2 params, no nested objects, annotations present), the description fully covers the how, when, and what: natural language query, return format with schemas and examples, and call-first strategy. No output schema needed because description specifies return contents.

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?

Input schema coverage is 100%, so baseline is 3. Description adds natural language examples for 'query' and mentions default/max for 'limit', but does not significantly extend beyond the schema's descriptions. Adequate but not exceptional.

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?

Describes the tool's verb ('Find') and resource ('tools') with specificity: it discovers tools by describing data or task. Clearly distinguishes from siblings like 'entity_profile' or 'validate_claim' by framing itself as a discovery/disambiguation tool to call first.

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 instructs when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides concrete scenarios like browsing SEC filings, FDA drugs, etc., and implies when not to use (when you already know the tool).

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds context about patent API being sunset, LEI via GLEIF, and date-sorted fundamentals. 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?

The description is detailed but front-loaded with purpose. Could be slightly more structured, but every sentence adds value. 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?

Given no output schema, description fully details the return structure including CIK, filings with URIs, fundamentals with date caveat, patents status, news fallback, and LEI. Complete for a 2-param 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?

Schema covers both parameters with descriptions. Description adds that type is currently only 'company' and value accepts ticker or zero-padded CIK, and explicitly states names not supported.

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 'Get everything about a US public company in one call' and lists specific use cases like 'tell me about X'. It distinguishes from siblings by noting that names require resolve_entity first.

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

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

Explicitly says when to use: 'Use when a user asks...' and when not to: 'names not supported (use resolve_entity first)'. Also provides alternative tool name for name resolution.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description confirms deletion but adds no extra behavioral nuance beyond what annotations convey.

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

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

Two sentences, front-loaded with action, no fluff. Every word 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?

Simple tool with one required parameter. Description covers purpose, usage guidance, and parameter usage. No output schema needed.

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% with description 'Memory key to delete'. Description says 'by key' which aligns but adds no new 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 the action (delete), resource (memory), and method (by key). It distinguishes itself from siblings like 'remember' and 'recall' by mentioning pairing.

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 provides conditions for use: context stale, task done, clearing sensitive data. Also notes pairing with remember and recall.

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 readOnly, idempotent, and non-destructive behavior. The description adds value by detailing the extraction process (fetches page, extracts title/description/key links) and output format (text blob for site-root/llms.txt), which goes 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 concise with no wasted words. It front-loads the core purpose and efficiently covers output and use cases in a few sentences.

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

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

For a simple fetch-and-format tool, the description is complete: it explains the operation, output format, and practical use cases. No output schema exists, but the description adequately describes the return type.

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% with clear parameter descriptions. The description does not add additional semantic meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb and resource. It uniquely identifies its function among sibling tools like ai_visibility_check and scan_competitor_ai_presence.

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 lists explicit use cases: indexing client sites, drafting llms.txt, or auditing AI crawler view of competitors. While it doesn't state when not to use it, the contexts are clear and sufficient for 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety and idempotency. The description adds value by explaining the behavior of constructing the series key, the business-day spot nature, and the meaning of the returned value. This exceeds the annotation baseline.

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 sentences plus an example, with no wasted words. It front-loads the main purpose and includes critical details about the rate direction and series key. Every sentence earns its place.

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

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

Given the low complexity of the tool, comprehensive annotations, and 100% schema coverage, the description adequately covers the tool's purpose, usage, and behavioral details. It explains the key behavioral traits (series key construction, quote direction, parameter interactions) sufficiently for an agent to select and invoke 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?

Input schema coverage is 100%, and the description adds meaning beyond the schema by explaining the series key construction, the interaction between last_n and start_period (last_n is overridden if start_period is set), and providing example currency codes. This adds useful context that helps the agent understand parameter 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 the tool retrieves the latest (or last N) Norges Bank exchange rate for a currency against NOK, with explicit examples of currency codes and the quote direction (how many NOK per unit of base currency). It uses a specific verb ('get') and resource ('exchange rate'), and the purpose is distinct 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 provides context on building the EXR series key and the meaning of the rate, but does not explicitly state when to use this tool over alternatives or when not to use it. No comparison with sibling tools or exclusion criteria are given.

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, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral details like the key format (dot-separated, wildcard allowed) and that it fetches data, which complements the annotations without 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 and front-loaded with the main purpose. It includes examples that are helpful without being verbose. Slightly more structured formatting could improve readability, but it is already 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 5 parameters and no output schema, the description adequately covers usage with examples and references to list_flows. It does not explain return format or pagination, but the annotations cover safety traits, making it sufficiently complete for an agent.

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% with descriptions for all parameters. The description adds value by explaining the key parameter's syntax and providing examples for flow_ref, going beyond the schema's simple descriptions.

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

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

The description clearly states it fetches SDMX data from any Norges Bank flow, with specific examples and a reference to list_flows for available flows. The verb 'get' and resource 'series' are 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 gives examples of when to use (e.g., for exchange rates, interest rates) and points to list_flows for available references. However, it does not explicitly state when not to use it or contrast with siblings like get_exchange_rate, which could be more specific.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, fully covering the safety profile. The description adds only that it returns dimension order, which is minimal behavioral context beyond the annotations.

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

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

Single sentence, no waste, front-loaded with purpose. Every word earns its place.

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

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

For a simple listing tool with no parameters, the description covers the purpose and return value (list of data flows with dimension order). No output schema, but the description compensates adequately. Complete for the complexity level.

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

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

There are zero parameters, so according to guidelines baseline is 4. The description does not need to add parameter meaning since there are none.

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

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

The description clearly states the tool lists Norges Bank SDMX data flows and includes dimension order. It uses a specific verb-resource combination and distinguishes from sibling tools like get_series which retrieve individual series data.

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 as a discovery tool for available data flows, but there is no explicit guidance on when to use it versus alternatives or any exclusions. The context is clear but lacks explicit direction.

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 no safety hints; description compensates by disclosing rate limit (5/identifier/day), free usage, and that feedback is read by the team daily. Lacks detail on whether feedback is anonymous or asynchronous but 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?

Well-structured with purpose first, followed by usage cases, then constraints. Every sentence adds value with no redundancy or filler.

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

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

Given no output schema and reasonable complexity, description covers all key aspects: purpose, usage scenarios, parameters, constraints, and formatting guidance. No gaps for effective tool 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 coverage is 100%; description adds meaning by explaining the enum values in practical terms (e.g., 'bug = something broke') and constraining message length (2000 chars). Improves understanding beyond schema alone.

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: collecting feedback (bug, feature, data_gap, praise) for Pipeworx team. It uses specific verbs and resources and distinguishes from sibling tools which are analysis or retrieval 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?

Explicitly states when to use each feedback type and warns against pasting end-user prompts. Also mentions rate limits and that it doesn't count against tool-call quota, providing clear context for usage.

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, open-world, idempotent, non-destructive. Description adds derivation source (CF analytics-engine), no PII, and caching behavior (5min-1h). 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?

Description is well-structured with bullet points for use cases. Front-loaded with main action. Slightly longer but each 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?

For a simple tool with one enum parameter and no output schema, the description is complete: it explains what is returned, how it works, privacy, and caching. No gaps.

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

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

Single parameter 'window' with full enum and description. Description adds semantic nuance: shorter windows surface current hotness, longer windows show steady-state demand. Schema coverage is 100%.

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 returns top tools, top packs, and total call volume over a recent window. Lists three specific use cases. Distinct from siblings like discover_tools or recent_changes.

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 explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case). Does not explicitly mention when not to use, but context is clear enough.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details beyond annotations, such as the two modes, partition_check logic, placeholder filtering, and similarity requirements. It aligns with annotations and enriches the agent's understanding of the tool's behavior.

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

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

The description is information-dense but somewhat verbose, especially in explaining cross-event mode and partition checks. It front-loads the core purpose and modes, but some sentences could be tightened. Still, it is structured logically and contains no irrelevant information.

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

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

Given the tool's complexity (two modes, cross-event logic, partition checks, filter conditions), the description is remarkably complete. It covers not only what the tool does but also how each mode works, constraints, and the shape of the response (opportunities[], partition_check). Despite the lack of an output schema, the agent has enough context to use 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?

Input schema has 100% coverage with descriptions for both parameters. The description adds significant meaning beyond the schema, explaining the context of each parameter, how they correspond to modes, and provides examples. This exceeds the baseline expectation for high 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?

The description explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) and explains what each does, effectively differentiating from sibling tools like polymarket_edges or polymarket_kalshi_spread.

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

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

The description provides clear guidance on when to use each mode (event vs topic) and the benefits of cross-event mode ('catches ... patterns that single-event misses'). It also explains constraints like Jaccard similarity threshold and placeholder filters. However, it does not explicitly state when not to use the tool or suggest alternatives, which slightly detracts.

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, openWorldHint, idempotentHint, and destructiveHint are all set appropriately. The description adds rich behavioral context: caching (1h KV level), edge calculation (net of slippage, Kelly caps at 0.25), per-leg favorite-longshot bias correction, placeholder-slug filters, and exclusion of fed_rate bets. 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 detailed and front-loaded with the main purpose. While long, every sentence adds value for a complex tool. Minor redundancy could be trimmed (e.g., repeating tradeable-edge knobs), but overall well-organized.

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 covers all essential aspects: three model families, edge fields (edge_pp_net, kelly_fraction, liquidity, spread), tradeable-edge knobs, caching, and exclusions. The fed_rate exclusion with a pointer to another context is a nice touch. Complete for a complex, parameter-rich 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?

Schema coverage is 100%, so baseline is 3, but the description adds substantial meaning beyond schema: explains min_kelly as half-Kelly fraction, edge_pp net of slippage, slippage_pp with practical context (Polymarket has zero fees but bid/ask spreads), max_spread_pp and min_liquidity with concrete examples, and min_partition_leg_kelly's distinct purpose. This elevates the score to 5.

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

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

The description explicitly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a clear use case ('what should I bet on today'). It details three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from sibling tools like polymarket_arbitrage.

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 use the tool ('agents discover opportunities without paging hundreds of markets') and provides tradeable-edge knobs (min_liquidity, max_spread_pp) that help filter unrealistic edges. It also notes that fed_rate bets are excluded from ranking, but does not explicitly contrast with alternatives like polymarket_arbitrage or bet_research.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the return format (leg-by-leg prices, spread in percentage points) and the underlying reason for price differences. 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?

The description is a single paragraph that is front-loaded with the main purpose, followed by explanatory context and modes. It is informative but could be slightly 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?

With no output schema, the description adequately explains the return values. It covers both modes but does not specify behavior when no parameters are provided (all optional). Given high schema coverage and annotations, it is largely complete.

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

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

The input schema covers all three parameters with descriptions. The tool description adds context on how parameters interact (topic vs explicit, overriding), and provides examples in the schema. This adds value beyond the schema alone.

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 computes cross-venue spreads between Kalshi and Polymarket for the same event. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue arbitrage, and explicitly mentions two modes of operation.

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

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

The description provides clear guidance on when to use each mode (topic shortcuts for quick lookups, explicit tickers for custom pairs). It explains the context of price differences, but does not explicitly mention when not to use the tool or compare to sibling 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 idempotentHint=true, and the description adds scoping info (anonymous IP, BYO key, account ID). 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?

Three sentences, front-loaded with core action, and provides useful context without redundancy. Efficient for the information conveyed.

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?

Although no output schema, the description covers functionality, use case, and scoping. Sufficient for a straightforward retrieval tool given annotations.

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 already describes the key parameter's omission to list keys. Description repeats this but adds no new semantic value beyond 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 retrieves values saved via remember or lists all keys when omitted, distinguishing it from siblings like remember and forget. It uses specific verbs and resource.

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 on when to use (look up stored context without re-deriving) and pairs with remember/forget, but doesn't explicitly exclude alternatives. Adequate for a simple tool.

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

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

Annotations already indicate read-only and non-destructive behavior. Description adds details on parallel execution, fallback from GDELT to GNews, and soft-fail for USPTO. Transparent about limitations like PatentsView API sunset.

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 a single concise paragraph, front-loaded with purpose and examples. Every sentence adds value without redundancy.

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

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

Despite no output schema, description fully covers return structure (grouped changes, count, citation URIs) and explains all three sources and fallback logic. Complete for a complex 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?

Schema coverage is 100% with descriptions, but description enriches with examples for 'since' (ISO date or relative shorthand) and clarifies 'value' accepts ticker or CIK. Adds context beyond 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 the tool fetches recent changes for a company over a time window, with example queries. Distinguishes from sibling entity_profile by contrasting static vs. dynamic nature.

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 advises when to use this tool vs. entity_profile. Provides example use cases like 'news on Apple this month' and explains parallel fan-out to multiple sources.

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?

Discloses scoping by identifier, persistence based on authentication (persistent for authenticated, 24h for anonymous), and pairs with recall/forget. These details go beyond annotations which only indicate idempotent and non-destructive.

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?

Concise (5 sentences), well-structured: purpose first, then use cases, then technical details, then pairing. No superfluous 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?

Covers all relevant aspects: storage mechanism, scope, retention, and companion tools. No output schema needed. Given schema and annotations, description fills important gaps.

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

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

Schema already has detailed descriptions for key and value (100% coverage). The description does not add new parameter information beyond what the schema provides, so 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 clearly states the tool saves data for reuse later, with concrete examples like ticker, address, preference. It distinguishes from recall and forget, and explicitly says it's a key-value store scoped by identifier.

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 explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with examples. Directly pairs with recall and forget, making alternatives clear.

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

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

The description goes well beyond annotations by detailing internal cascade through multiple endpoints, returning citation URIs, and auto-disambiguation for companies. Annotations already indicate read-only, idempotent, open-world, and non-destructive, and the description adds valuable behavioral context without 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?

Every sentence is purposeful: the opening states the overall goal, 'Use FIRST' gives priority guidance, then bullet-like details for each type, and a final note on internal efficiency. No redundant or vague statements, well-structured for quick scanning.

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

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

Given the tool's complexity (two entity types, multiple input forms, rich outputs including citations, no output schema), the description covers everything: purpose, when to use, input flexibility, return structure, and underlying behavior. It fully equips an AI agent 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 100%, but the description adds substantial meaning: for 'company' it clarifies inputs (ticker, CIK, name) and outputs (ticker, CIK, company_name, citation); for 'drug' it specifies inputs (brand/generic name) and outputs (RxCUI, ingredient, brand, citation). This fully compensates for the minimal schema descriptions.

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

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

The description clearly states it resolves user-spoken names to canonical IDs needed by other tools. It specifies two supported types (company, drug) and what each returns, distinguishing it from sibling tools like 'entity_profile' or 'compare_entities' which operate on already-resolved entities.

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

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

Explicitly says 'Use FIRST when you have a name but need an ID', providing clear when-to-use guidance. It does not explicitly list when not to use, but the context implies if you already have an ID you don't need this. The mention of replacing 2-3 manual lookups adds efficiency guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, signal density. 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?

Four sentences, no wasted words. The main purpose is front-loaded. Every sentence adds value: purpose, how it works, use case, output details.

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

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

Given full schema coverage and annotations covering safety/idempotency, the description adequately explains behavior, use case, and output (ranked list with score/confidence/signal density). No output schema needed beyond what's described.

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%, but description adds nuance: models are 'which models to probe', _apiKey is 'optional for Anthropic', context 'disambiguates common names', and entities 'first entry treated as subject'. This goes beyond mere repetition of schema descriptions.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb 'compare', resource 'AI visibility', and action 'side-by-side', distinguishing it from sibling 'ai_visibility_check' which is for single entities.

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 clear use case: 'Useful for competitive AI-marketing audits' and gives an example question. It implies when to use (compare multiple entities) and hints at alternatives (ai_visibility_check for single), though lacks explicit 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. The description adds value by detailing the return format (verdict, structured form, actual value with citation, percent delta) and explaining it consolidates multiple sequential calls.

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 succinct, front-loaded with purpose, then usage, then details. No fluff, 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 no output schema, the description fully explains the return values. Annotations cover safety and behavior. Completes the picture for a single-parameter 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?

Schema coverage is 100% with a description for the only parameter. The description adds natural-language examples and context, slightly 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's purpose: fact-checking natural-language claims against authoritative sources, with specific focus on company-financial claims via SEC EDGAR + XBRL. It distinguishes from siblings by noting it replaces multiple sequential calls.

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

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

The description provides clear when-to-use guidance with example queries. It specifies the current scope (v1 supports company-financial claims), implying limitations, but does not explicitly list alternative tools for other domains.

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