Istat It

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the default model is free, Anthropic requires BYO key, and returns per-model details (score, confidence, signals, raw_response) plus combined view. 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?

Four sentences, front-loaded with action and result. Every sentence provides valuable information: purpose, default model, API key requirement, return structure, and use cases. 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?

Despite no output schema, the description explains return values (per-model score, confidence, signals, raw_response plus combined view). Covers required param (entity), optional params (models, _apiKey, context), and default behavior. Usage examples like 'Pipeworx' help. 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%, so baseline is 3. The description adds context: explains entity with examples, models array with supported values, _apiKey optional only for Anthropic with pass-through detail, and context for disambiguation. This goes beyond the schema's 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 probes LLMs for knowledge about an entity and returns a visibility score. It specifies verb 'probe', resource 'one or more LLMs', and output 'score (0-100)'. It distinguishes from siblings by focusing on scoring visibility across multiple models, unlike 'scan_competitor_ai_presence' which likely has a different 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 explicitly states when to use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It does not explicitly say when not to use or mention alternatives, but the context is clear enough. The sibling 'scan_competitor_ai_presence' might be an alternative, but no direct comparison is made.

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, destructiveHint=false. The description adds valuable context: routes to 2,866 tools across 623 sources, returns structured data with stable 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?

The description is somewhat lengthy but well-organized: starts with strong directive to prefer over web search, then lists use cases and examples. Could be slightly trimmed but every sentence adds important contextual 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 single parameter, no output schema, and comprehensive annotations covering safety, the description is complete. It fully explains the tool's scope, usage guidance, and provides concrete examples, leaving no 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?

Only one parameter 'question' with schema description 'Your question or request in natural language'. Schema coverage is 100%. The description adds value through extensive examples (over 10 question examples) that illustrate acceptable inputs 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 explicitly states it is a routing tool for factual questions, distinguishing it from web search. It lists specific domains (SEC, FDA, etc.) and provides concrete examples, making the purpose highly clear.

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 'PREFER OVER WEB SEARCH' and lists many query types including 'what is', 'look up', etc. It does not explicitly say when not to use, but the preference is strongly stated and the 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 indicate readOnlyHint=true, openWorldHint=true, etc. The description adds extensive behavioral detail: classifiers, fan-out logic, response shape with market/analysis/evidence fields, safety short-circuits for low-confidence matches, closed markets, and illiquid wide spreads. 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 fairly long but well-structured with clear sections: purpose, classifiers, fan-out examples, response shapes, safety notes. It is front-loaded with the main action. Some details (like individual fan-out examples) could be condensed, but overall it's efficient for the complexity.

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 (classifiers, multiple data sources, safety conditions), the description covers all essential context: input types, processing pipeline, response format, edge cases (low confidence, closed markets, wide spreads). No output schema is present, but the response shape is described in sufficient detail.

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% for the 3 parameters (market, depth, include_raw). The description adds beyond schema by explaining how to use the market parameter (slug, URL, question text) and the behavioral differences between 'quick' and 'thorough' depth, and when to use include_raw=true. This adds meaningful guidance.

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 researches a Polymarket bet by pulling Pipeworx data, specifying inputs (slug, URL, question text) and outputs (evidence packet + comparison). It distinguishes itself from sibling tools like polymarket_edges or polymarket_arbitrage by its comprehensive data aggregation and classification.

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 to use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides classifiers and fan-out examples, helping the agent decide when to invoke. However, it does not explicitly mention when not to use this tool versus alternatives.

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

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

Annotations indicate read-only, open-world, and idempotent. The description adds significant behavioral context: it explains the fix for accurate fiscal year data, handling of off-calendar fiscal years, and the output format (paired data with citation URIs). 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 and front-loaded with the purpose and common queries. Every sentence adds value, explaining data sources, fixes, and output. It avoids redundancy and is well-structured.

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 main functionality, data sources, and output format. It lacks details on error handling or missing entities, but given the complexity (two entity types, multiple metrics), it is fairly complete. No output schema shifts burden to description, which handles it well.

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. The description adds semantic value by explaining the type parameter's enum values ('company' pulls SEC data, 'drug' pulls FAERS) and provides examples for the values parameter (tickers/CIKs vs drug names). This exceeds the baseline 3 for 100% 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 clearly states the tool compares 2-5 companies or drugs side by side, identifying specific use cases like 'compare X and Y' or 'which is bigger'. It specifies data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs) and output features, distinguishing it from siblings like entity_profile or resolve_entity.

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 this tool: for comparative questions, ranking, or 'X vs Y'. It mentions it replaces 8-15 sequential lookups, justifying its use. However, it does not provide explicit exclusions 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context about the ordered dimensions and key positions, which goes 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?

Extremely concise: two sentences plus an inline example. Front-loaded with purpose and 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?

For a simple tool with one parameter, good annotations, and no output schema, the description provides complete context about what the tool does and how its output is used.

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 100% with a clear description and example. The tool description reinforces the parameter usage with an example but adds minimal additional 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 gets the structure (Data Structure Definition) of an ISTAT dataset, including ordered dimensions and valid codes, which distinguishes it from siblings like get_data and list_dataflows.

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 to use this tool to learn how to build the SDMX key for get_data, and provides an example. While it doesn't mention when not to use it, the 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 already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds important behavioral details: it returns top-N tools with full schemas, and each result is ready to call directly without a second lookup. It does not mention any side effects or limitations, but given the annotations cover the key traits, this is sufficient.

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

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

The description is concise and well-structured. It front-loads the core purpose, lists relevant domains, and then explains the output format and when to use. Every sentence adds necessary context without redundancy.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description fully covers what the agent needs to know: what it does, what it returns, and when to use it. The list of example domains provides rich context for the agent to formulate queries.

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% for the two parameters (query and limit). The description adds value beyond the schema by providing concrete query examples and clarifying the default limit (20) and maximum (50). This helps the agent form better queries.

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: 'Find tools by describing the data or task.' It lists many specific use cases (SEC filings, financials, FDA drugs, etc.) and explains the return format (top-N most relevant tools with names, descriptions, and full input schemas). This makes it distinct from sibling tools, which are domain-specific tools, while discover_tools is a meta-tool for exploration.

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: 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear guidance on prioritizing this tool over alternatives, and the description includes examples of queries to guide the agent.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details return fields, including caveats like 'patents pack soft-fails until reactivated' and 'fundamentals... not stale FY2022'. This adds significant behavioral context.

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

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

The description is well-structured with a clear purpose statement, usage guidelines, and return details. However, it is somewhat lengthy (150+ words) and could be trimmed 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 the tool's complexity (multiple data sources), no output schema, the description thoroughly explains return fields, limitations (patents sunset), and edge cases (name unsupported). It feels complete for an agent to use 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 100%, and the description adds extra meaning: type is limited to 'company', and value explains ticker/CIK format with explicit instruction to use resolve_entity for names. This goes beyond repeating 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 'Get everything about a US public company in one call' and specifies when to use it (e.g., 'tell me about X', 'research Acme'). It distinguishes itself from sibling tools like resolve_entity and compare_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?

Explicit use cases are given ('when a user asks...'), and the description advises against using names, directing to resolve_entity instead. It also specifies acceptable inputs (ticker or CIK).

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 aligns with annotations (destructiveHint true, idempotentHint true) and adds context about clearing sensitive data. 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 sentences, no extraneous information. Every sentence adds value: first states purpose, second provides usage guidelines.

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 one-parameter tool with no output schema, description covers purpose, usage, and behavioral context. 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?

Only one parameter 'key' with schema description 'Memory key to delete'. Schema coverage is 100%, but tool description does not add additional 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?

Description explicitly states 'Delete a previously stored memory by key', clearly specifying verb and resource. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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 scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. Also explains relationship with siblings: 'Pair 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, all consistent with the description of fetching a page and emitting text. The description adds behavioral detail like 'Fetches the page, extracts title/description/key links' and 'Output is a single text blob', which goes beyond 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?

Two focused sentences plus a bullet list of use cases. Every sentence adds distinct information: action, process, output format, and usage scenarios. No fluff, well-structured for quick parsing.

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

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

Given only 2 parameters, no output schema, and simple behavior, the description fully covers what the tool does, what it returns (text blob), and where to place the result. It leaves no significant gaps for an agent to infer.

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 (url and max_links) with descriptions. Description adds value by specifying the default for max_links (25) and max (50), but the schema already explains what each parameter is. Since schema coverage is 100%, the description's added context is useful but not critical.

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 the tool generates an llms.txt file for any URL, specifying the exact actions (fetch, extract title/description/links, emit standard format) and the resulting output (text blob for site-root/llms.txt). This differentiates it from siblings like ai_visibility_check or scan_competitor_ai_presence, which have related but distinct 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?

Description lists three concrete use cases: client indexing, personal project drafting, and competitor audit. It doesn't explicitly state when not to use or compare to alternatives, but the use cases provide clear guidance. Missing explicit 'when-not' and alternative recommendations, but the context is sufficient for most agents.

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, and no destructiveness. The description adds behavioral traits such as the key format (dot-separated SDMX filter), wildcarding, and the return of decoded series with labels, which are not covered by annotations.

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

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

The description is concise, front-loaded with the main purpose, and every sentence adds value. It includes an example that efficiently demonstrates usage without unnecessary elaboration.

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 explains the return format (decoded series with dimension labels and per-period values), covers key parameter behaviors, and includes a caution about large datasets, making it complete for a data retrieval 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%, but the description adds substantial meaning beyond the schema by explaining the key parameter format with an example, detailing the effect of omitting parameters, and clarifying the purpose of dataflow_id and time periods.

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 'Pull observations from an ISTAT dataset', with a specific verb and resource. It distinguishes itself from sibling tools like dataflow_structure by focusing on data retrieval rather than metadata.

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, including a caution about fetching all series being potentially large. However, it does not explicitly mention when not to use it or alternatives to 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 the tool as read-only and idempotent. The description adds context about the large number of datasets and the need for filtering, which helps set expectations. 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 at 4 sentences, front-loading the purpose and ending with clear examples. No unnecessary content.

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

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

For a list tool with two simple parameters and good annotations, the description covers purpose, usage, and dataset volume. It lacks details on pagination or result structure beyond id and name, but this is likely sufficient.

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 schema already documents both parameters. The description reinforces the default limit and provides examples, but does not add new semantic information 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 browses or keyword-searches ISTAT datasets, with explicit reference to the sibling tools get_data and dataflow_structure for further use. This distinguishes 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?

The description advises passing a query to filter the 4,800 datasets, and provides an example. It implicitly guides the agent to use this tool for discovery before calling get_data or dataflow_structure, though it does not explicitly list 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?

Description discloses non-obvious traits beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, team reads digests daily, signal affects roadmap. No contradiction with annotations (readOnlyHint=false is consistent with sending feedback).

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 paragraph of 6 sentences, front-loaded with purpose, then use cases, formatting, business context, constraints. Every sentence is meaningful and relevant. 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?

With 3 parameters, 1 enum, nested object, and no output schema, the description covers input semantics, usage scenarios, formatting, rate limits, and impact. No missing critical information for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by explaining enum values for 'type' and giving best practices for 'message' (be specific, 1-2 sentences). 'context' is described as optional with examples. Slight enhancement over 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?

Description clearly states it's for providing feedback (bugs, features, data gaps, praise) to the Pipeworx team. Uses specific verbs and resources, and distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on feedback rather than queries or tool discovery.

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 lists when to use (bug, feature/data gap, praise) and provides formatting instructions (describe in terms of Pipeworx tools/packs, avoid pasting prompts). Includes business context (team reads digests, affects roadmap) and constraints (rate limit, free, no quota impact).

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 behavior. The description adds critical behavioral details: data source (CF analytics-engine), no PII, caching strategy (5min-1h). 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?

Compact and well-structured. First sentence captures essence, followed by numbered use cases. No redundant information; 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?

Given the simple tool (1 param, good annotations), the description covers purpose, usage, data origin, privacy, and caching. No major 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% with one enum parameter. Description adds semantic guidance ('Shorter windows surface what's hot... longer windows show steady-state demand'), enhancing understanding beyond schema enumeration.

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 'top tools, top packs, and total call volume' over configurable windows. It distinguishes itself from siblings like 'discover_tools' by focusing on popularity signals from other AI agents.

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 lists three use cases: discovering hot data sources, confirming canonical tools, and alignment checks. However, it does not mention when not to use or compare with alternatives like 'discover_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?

Adds context beyond annotations: describes internal logic (monotonicity checks, Jaccard similarity, partition filter), response structure, and edge cases. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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 clear separation of modes and technical details. Front-loaded with main purpose. Slightly verbose but every sentence adds value; could be tightened.

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 explains response fields (opportunities[], gap_pp, suggested_trade, reasoning, partition_check). Covers edge cases (similarity threshold, placeholder filters). Complete for an arbitrage detection 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?

Even with 100% schema coverage, description adds significant meaning: explains event is for single-event mode, topic for cross-event mode, provides examples, and details filtering logic (placeholder removal, similarity threshold). Greatly aids correct 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?

Description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes two modes (event and topic) and differentiates from sibling tools like polymarket_edges and 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?

Provides clear guidance on when to use each mode (event slug vs topic) with examples. Mentions cross-event mode catches patterns single-event misses, but does not explicitly state when not to use the tool or alternatives.

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

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

Annotations indicate read-only, open-world, and idempotent. The description adds that the tool is cached 1h at KV level keyed on all knobs, and explains behavioral quirks like news_momentum having halved Kelly. 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 detailed and well-structured, starting with purpose, then model families, then output fields, then knobs, and finally exclusions. While dense, it front-loads key information and avoids 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 no output schema, the description explains the output structure including fields like edge_pp_net, kelly_fraction, and market details. It covers caching, fed_rate exclusion, and tradeable-edge filters. For a complex tool with 9 parameters, it is fairly 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% with detailed descriptions for each parameter. The description does not add significant extra meaning beyond the schema, but it does provide context on how knobs like 'min_liquidity' relate to execution feasibility. 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes from sibling tools by mentioning Pipeworx data and the segmented model families.

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 it's for daily bet discovery without paging hundreds of markets. It explains tradeable-edge knobs and mentions that fed_rate bets are excluded. However, it doesn't explicitly contrast with alternatives like polymarket_arbitrage.

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. The description adds significant behavioral context: it computes spreads, returns leg-by-leg prices, and explains the typical 2-25pp delta due to participant pools. This fully informs the AI of what the tool does 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 a single paragraph that front-loads the purpose and then details modes and return format. It is informative without unnecessary repetition, though slightly long at ~150 words. Could be tightened but remains clear and well-structured.

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 fully explains return values (leg-by-leg prices and spread). It covers both modes, enumerates topic shortcuts, and clarifies parameter precedence. Given the tool's complexity and sibling tools, this is 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 two modes, that explicit parameters override the topic-mapped side, and enumerates all topic values. This provides guidance beyond the schema's property 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It explains two modes (topic shortcuts and explicit pairing) and distinguishes itself from siblings like polymarket_arbitrage by specifying the unique cross-venue arbitrage signal.

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 each mode: topic for pre-mapped macros and explicit for custom pairings. Examples are given. It does not explicitly state when not to use the tool or compare to alternatives, but the context is clear enough for an AI to decide.

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 safety profile (read-only, idempotent). Description adds scope (identifier-based) and listing behavior, enriching 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, front-loaded with core action, every sentence adds value, no 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?

Complete for a simple tool: clarifies purpose, usage, scope, and siblings. No missing aspects given annotations and schema.

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 100% of parameters. Description adds real-world examples and clarifies usage, adding 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 retrieves a saved value or lists all keys, explicitly distinguishing from siblings 'remember' and 'forget'.

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

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

It tells when to use (look up stored context), how (omit key to list), and pairs with remember/forget for a complete workflow.

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 the tool safe (readOnlyHint, idempotentHint, etc.), but the description adds valuable detail: parallel fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail until reactivated, and structured return format. 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 informative and well-structured: general purpose, then source details, parameter syntax, return format, and alternative tool. Each sentence adds value, but the length could be slightly trimmed 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 no output schema, the description explains the structured return type (changes grouped by source, total_changes, pipeworx URIs). It covers all three data sources, their fallback behavior, and a soft-failure condition. It also suggests the appropriate alternative 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%, baseline 3. The description adds practical context: `since` accepts ISO date or relative shorthand with examples, `value` can be ticker or CIK, and `type` is restricted to 'company'. This goes well beyond the 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 starts with a clear action ('What's new with a company') and lists specific use cases ('what's happening with X', 'updates on Y', etc.). It explicitly distinguishes itself from the sibling tool 'entity_profile' by contrasting static vs. dynamic queries.

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

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

It provides explicit when-to-use scenarios (change-monitoring, news) and when-not-to-use (use entity_profile for static data). It also explains fallback behavior between GDELT and GNews, and notes the USPTO soft-failure.

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?

Adds useful context beyond annotations: key-value pair scoped by identifier, persistence details (24 hours for anonymous, persistent for authenticated), and implied idempotency. Annotations already cover idempotentHint=true and readOnlyHint=false consistently.

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 succinctly convey purpose and usage, with additional behavioral context and tool pairing. 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?

Complete for a simple storage tool: explains what, when, how it works, and integration with siblings. 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 has 100% coverage with descriptions; description adds concrete examples for key and value, enhancing semantic understanding 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 'Save data the agent will need to reuse later' with specific verb and resource. Distinguishes from sibling tools recall and forget by mentioning them explicitly.

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

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

Provides clear guidance on when to use (discover something worth carrying forward) and examples, but lacks explicit when-not-to-use or alternatives beyond recall/forget.

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, idempotent, non-destructive behavior. The description adds value by revealing that each call cascades through multiple internal lookups, replacing 2-3 manual steps. This explains internal complexity and efficiency 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 (~100 words), front-loaded with purpose and usage, and well-structured with bullet-like formatting for types. Every sentence adds value, 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?

Despite lacking an output schema, the description thoroughly explains what each entity type returns (identifiers, citation URIs). It also notes internal lookups and efficiency gains. Combined with 100% schema coverage, the description is complete for the tool's complexity.

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 description enriches both parameters: 'type' is explained with supported values and corresponding output details (e.g., ticker, CIK for company; RxCUI for drug), and 'value' provides clear examples and acceptable formats. This goes well beyond the schema's minimal 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: resolving user-spoken names to canonical identifiers. It specifies the verb 'resolve' and resource 'names to IDs', and distinguishes from sibling tools (e.g., entity_profile, compare_entities) by focusing on identifier resolution rather than analysis.

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 FIRST when you have a name but need an ID', providing clear context for usage. It does not explicitly state when not to use or mention alternatives, but the sibling set lacks other resolvers, making this 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 already declare it read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it probes each entity, ranks by score, and returns a ranked list with score, confidence, signal density per entity. 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 two sentences, front-loading the core purpose and expanding on use case and return format. No extraneous words; 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?

No output schema exists, so description fully explains return values (ranked list with score, confidence, signal density). It covers purpose, usage, parameters, internal process, and return format. For a comparative analysis tool with 4 parameters and clear annotations, this is 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 nuance for the 'entities' parameter (first entry treated as subject), but does not significantly enhance understanding of 'models' or '_apiKey' beyond the schema. It adds some value without compensating for a coverage 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 compares AI visibility across multiple entities side-by-side, introduces the verb 'compare', specifies the resource 'AI visibility', and distinguishes from the sibling tool 'ai_visibility_check' which likely handles 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 for competitive AI-marketing audits with an example question ('does Claude know about us as well as our competitors?'). It explains the process (probes each entity with ai_visibility_check), but does not explicitly exclude alternative tools like 'compare_entities' or state 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?

Beyond the annotations (readOnly, idempotent, etc.), the description adds key behavioral details: supported claim types, data sources (SEC EDGAR + XBRL), return values (verdict, citation, percent delta), and efficiency gains. This provides a comprehensive picture of what the tool does and how it behaves.

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—five sentences covering purpose, usage, scope, output, and value—with no redundant information. It is well-structured and front-loaded with the action verb.

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 simple input schema and no output schema, the description adequately covers input, output, scope, and behavioral traits. It could detail the verdict categories slightly more, but the provided information is sufficient for an 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?

The single 'claim' parameter has 100% schema coverage with a clear description and examples. The tool description adds additional context (type of claims, examples) but does not significantly extend beyond the schema. 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 explicitly states the tool's purpose: 'Fact-check, verify, validate...' and specifies its scope (company-financial claims for US public companies). It clearly distinguishes from sibling tools like 'entity_profile' or 'get_data' by focusing on claim verification.

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 usage context ('use when an agent needs to check whether something a user said is true') with examples. It does not explicitly list when not to use or compare to alternatives among siblings, but the specificity makes the intended use case obvious.

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