Dbnomics

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

Annotations already declare safe, idempotent, read-only, open-world behavior. The description adds context about probing multiple models, scoring, and passing API key directly to Anthropic with user-paying model. No contradictions. Could mention rate limits or failure handling, but sufficient given annotations.

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

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

Two sentences: first states the core function and default model, second details optional probing and return format. Front-loaded with purpose, no filler words. Every sentence is meaningful and concise.

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 details the return structure: per-model {score, confidence, signals, raw_response} plus combined view. It covers purpose, usage examples, default behavior, and optional key usage. Complete for evaluating brand visibility in AI models.

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 four parameters. The description adds value beyond schema: it specifies the default model (Workers AI Llama-3.3-70b free), explains _apiKey usage ('passed straight through'), and clarifies context usage. This enriches parameter understanding 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 probes LLMs for knowledge about an entity and scores visibility per model. Uses specific verb 'probe' and resource 'LLMs'. Distinct from sibling tools like 'scan_competitor_ai_presence' which is more about scanning competitors, or 'compare_entities' which compares entities. Purpose is 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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains default model and optional API key for Anthropic. However, it does not explicitly state when not to use it or suggest alternatives among siblings, leaving some gaps in decision 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, destructiveHint. Description adds that the tool routes to 3899 tools across 932 sources, fills arguments, and returns structured answers 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?

Description is relatively long but well-structured: starts with a strong preference statement, lists data types, gives usage examples, then step-up guidance. Front-loaded with key information, though minor redundancy exists.

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 (one main parameter, no output schema), the description provides sufficient context: it explains the return format (structured answer with citation URIs) and when to use it. Missing details about rate limits or authentication but annotations cover safety.

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 and examples for the question parameter and its aliases. Description reinforces that it accepts natural language but does not add significant 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?

Description clearly states the tool is preferred over web search for factual questions about real-world data, listing specific domains (SEC filings, FDA, etc.) and providing examples. It distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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 to prefer this tool over web search, provides query patterns (e.g., 'what is', 'look up'), and specifies when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions).

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?

Describes the full workflow (routing, filling arguments, fetching, extracting from tool result), return format with refusal reasons, and cost tradeoff. Annotations already confirm read-only, idempotent, non-destructive; description adds essential behavioral details 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?

Single, well-organized paragraph that front-loads the purpose and key constraints. Every sentence adds value, and the return format and refusal reasons are clearly enumerated.

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 specifies the return object fields and all possible refusal reasons. It also mentions the extra LLM call cost, routing logic, and source count, making the tool behavior fully predictible.

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 all parameters described as aliases for 'question'. The description reinforces they accept natural language and lists all aliases, which adds marginal 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 is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling tool ask_pipeworx by noting it extracts answers using only tool results and returns explicit refusals.

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

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

Explicitly tells when to use: 'when an answer will be quoted, cited, or acted on, and the agent must not invent facts' and advises to 'prefer ask_pipeworx for casual lookups.' No ambiguity.

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 safe, read-only, idempotent behavior. The description goes far beyond, detailing the resolution contract (market_match_confidence, alternatives, suggestions), parent event extraction, news fallback fields, safety short-circuits, closed market handling, wide-spread warnings, and resolution-rule risk. This provides comprehensive behavioral transparency.

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 lengthy but front-loaded with the core purpose and use cases. Every sentence adds valuable information for such a complex tool. It could be more structured (e.g., bullet points for response shapes), but the prose is clear and organized. Justified for the level of detail needed.

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, no output schema, and rich response structure, the description covers everything: classifiers, fan-out examples, response shapes (market, analysis, evidence), resolver contract, parent event, news fields, safety, closed markets, wide spreads, and cancellation rules. It is complete for correct invocation and interpretation.

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 three parameters. The description adds significant value: explains that market can be slug, URL, or question text; depth options quick/thorough with default; include_raw default false with summary vs full payloads. This enriches parameter understanding 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (Polymarket bet), and distinguishes from siblings like polymarket_edges or polymarket_arbitrage by the scope of data retrieval.

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 provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Extensive examples of fan-outs and classifiers give clear context. However, it does not explicitly state when not to use this tool versus alternatives, which would strengthen the score.

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 value by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics, off-calendar fiscal year handling, sorted results, and citation URIs. It does not cover rate limits or error cases.

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 example queries and is fairly structured. Each sentence adds information, though it could be slightly more concise. 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, the description explains return format (paired data + citation URIs) and covers both entity types thoroughly. It addresses data handling nuances (fiscal years) and efficiency gains.

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 both parameters described. The description enriches meaning by explaining that 'values' are tickers/CIKs for companies and drug names for drugs, and provides context on data pulled per type.

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 performs side-by-side comparisons of 2-5 companies or drugs in one parallel call. It uses specific verbs like 'compare', 'pulls', and 'returns', and distinguishes from single-entity lookups by noting it replaces 8-15 sequential lookups.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries. It lacks explicit when-not-to-use guidance but implies not for single entities.

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, destructiveHint. The description adds critical context: account requirement, non-open-web nature, parallel tool routing (3,899 tools), result format (findings packet with gaps[]), and expected duration (15-60s). 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 lengthy but every sentence adds value. It is well-structured with clear sections: account requirement, alternative, what it does, how it works, results, usage conditions, and timing. Slightly verbose but appropriate given the tool 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 (2 parameters, no output schema), the description covers everything an agent needs: authentication, prerequisites, behavior, result format, expected time, and clear differentiation from siblings. No gaps remain.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains the 'depth' enum values (quick=3, standard=5, thorough=8) and that 'thorough' requires a paid plan. It also clarifies that the 'question' parameter works well with broad, multi-part 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 does 'grounded multi-source research across Pipeworx's 932 STRUCTURED data sources' in one call, distinguishing it from siblings like ask_pipeworx. The verb 'research' and resource 'structured data sources' are specific and 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?

Explicitly provides when-to-use (broad/multi-part questions over structured data), when-not-to-use (single lookup, breaking/current news), and alternatives (ask_pipeworx for those cases). Also mentions account requirements and that depth:'thorough' needs a paid plan.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying that the tool returns top-N relevant tools with full input schemas and curated examples, and that each result is ready to call directly. It also mentions default limit (20) and max (50). 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 concise: three sentences cover purpose, domain listing, return value, and usage advice. No fluff, front-loaded with key information. 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?

For a tool with 6 parameters (5 aliases), no output schema, and annotations covering safety, the description is complete. It explains what the tool returns (names, descriptions, full schemas with examples), the limit default/max, and the aliases for query. No additional context is needed for an agent 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?

Schema coverage is 100% with descriptions for all 6 parameters. The description adds context by listing example queries and noting aliases for query, but does not provide critical additional meaning 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?

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explicitly distinguishes from siblings by saying 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides a distinct purpose compared to sibling tools like search or deep_research.

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 provides clear context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when to use but does not explicitly state when not to use or name alternatives. Still, the guidance is strong and actionable.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description details the fan-out across multiple sources, return fields, USPTO sunset date and soft-fail, GDELT→GNews fallback, and parameter constraints. 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 efficiently packs details about sources, returns, and fallbacks. Front-loaded with examples. A minor reduction could improve conciseness, but 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 tool's complexity (multiple sources, fallback mechanisms, specific fields), the description is highly complete. Without an output schema, it explains return structure clearly, covering filngs, fundamentals, patents, news, and LEI.

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 adds further context: 'type' only 'company' supported, 'value' as ticker or CIK, and that names are not supported, enriching 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 uses concrete examples ('Tell me about X', 'company profile for Microsoft') to clearly state the tool provides a full cross-source profile of US public companies. It distinguishes itself from siblings 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?

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is needed, and warns that names are not supported, directing to use resolve_entity first. Provides clear when-to and when-not-to use 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds no additional behavioral details beyond stating it is a browse operation, which is consistent. 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: first states purpose, second gives usage guidance. No filler words. Perfectly concise and front-loaded.

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

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

Given the rich schema (100% coverage, nested objects), comprehensive annotations, and existence of output schema, the description is sufficient. It correctly emphasizes the filtering capability and use case. Could mention that observations param is optional to save bandwidth, but schema already notes that.

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 all parameters have detailed descriptions. The description adds no new meaning beyond what the schema provides (e.g., 'structured filters' is implicit in the dimension parameter). 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 verb 'browse' and the resource 'series with structured filters.' It distinguishes from siblings like get_series and list_datasets by specifying the use case: when you know provider+dataset and want to enumerate series by dimensions.

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 when this tool is useful ('when you know the provider+dataset and want to enumerate series by dimensions'), providing clear context. However, it does not explicitly state when not to use it or mention alternative tools, which would improve it further.

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 matches annotations (destructiveHint true, idempotentHint true) and adds context about clearing sensitive data. No contradictions, but does not add significant behavioral details 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 sentences, front-loaded with purpose, then usage, then pairing. No wasted words, efficient and clear.

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

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

Given the tool's simplicity (one parameter, no output schema, annotations present), the description fully covers what the agent needs: what it does, when to use, and relationships with siblings.

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 as 'Memory key to delete'. Description only mentions 'by key', which adds no new semantic meaning 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 'Delete a previously stored memory by key', specifying the verb and resource. It distinguishes from siblings by mentioning 'Pair with remember and recall', indicating this is the complementary deletion tool.

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 guidance on when to use: 'context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with remember and recall, providing 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 already indicate readOnly=true, idempotent=true, and non-destructive. Description adds value by explaining the process (fetches page, extracts title/description/key links) and output format, 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?

Description is a single paragraph of 3-4 sentences, front-loaded with the main action and then concise context. 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?

No output schema, but description clarifies output is a single text blob ready to drop at site-root/llms.txt. It covers the core behavior, though it could mention error handling or edge cases for completeness.

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

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

Schema coverage is 100%, so baseline is 3. Description for url provides an example (https://example.com) but this is also in the schema. For max_links, schema already mentions default 25 and max 50. Description adds no new semantic information beyond what schema provides.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, with specific verb 'generate' and resource. It distinguishes from sibling tools by focusing on a unique output format not covered by others in the sibling list.

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 provides explicit use cases: getting a client's site indexed, drafting for your own project, or auditing competitors. However, it does not mention when to avoid this tool or suggest alternatives among the sibling tools like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds context beyond annotations by specifying the identification scheme (provider, dataset, series_code) and the effect of the observations parameter. 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 consists of two concise sentences that front-load the purpose and provide essential details without any redundant or extraneous 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 availability of an output schema and rich annotations, the description covers the identification scheme and the optional observations parameter. It is sufficient for an agent to understand the tool's core functionality, though a brief example of usage could enhance completeness.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds no additional semantic detail beyond what is in the schema; it merely restates the identification tuple and observation flag. Baseline score 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 fetches a specific time series, identifies it by provider, dataset, and series_code, and mentions including observations for data points. This specific verb-resource pairing distinguishes it from sibling tools like find_series and search.

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

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

The description implies usage when the exact series identifier is known but does not explicitly state when to use this tool versus alternatives such as find_series or search. No exclusions or when-not guidance is provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds minimal behavioral context beyond 'list all datasets', such as not mentioning pagination behavior or how results are ordered. The annotations carry the burden, so this is adequate but not informative.

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, zero waste. The description is efficiently front-loaded with the core purpose.

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 presence of an output schema and rich annotations, the description is adequate but minimal. It does not explain aggregation behavior, response size, or error handling, which could be useful for a list endpoint.

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

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

With 100% schema description coverage, the parameters are already well-documented in the schema (provider, limit, offset). The description does not add additional meaning or context beyond what the schema provides, resulting in a baseline 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 action (list) and the resource (datasets) with a specific scope (from a given provider). It distinguishes itself from siblings like find_series, get_series, and list_providers by focusing on datasets per provider.

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

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

No guidance on when to use this tool versus alternatives like search or find_series. The description does not mention prerequisites, limitations, or scenarios where another tool would be more appropriate.

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

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

Annotations already provide comprehensive safety hints; description adds value by specifying the number of providers (80+) and the format of output (codes and names). 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, front-loaded with the main action, no unnecessary words.

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

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

Given the tool's simplicity (no parameters, output schema exists), the description fully covers what the agent needs to know.

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?

No parameters exist, so schema coverage is 100%. Baseline score of 4 applies as there is no need for additional parameter information.

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 lists all statistics providers with codes and names, and distinguishes from siblings by mentioning how to use the output with list_datasets and get_series.

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 to use provider codes with list_datasets and get_series, providing a clear usage context.

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

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

Annotations already indicate read-only, idempotent, non-destructive traits. Description adds behavioral context: returns active subscriptions by default, can include inactive via parameter. 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: first states purpose and output, second gives usage guidance. No wasted words, perfectly front-loaded.

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

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

Given one optional boolean parameter, strong annotations, and no output schema needed, the description fully covers what the tool does, what it returns, and when to use it.

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 single parameter. Description does not add extra meaning beyond the schema for the parameter itself, but mentions return fields which aids understanding.

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 lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It differentiates from sibling tools like subscribe/unsubscribe by focusing on listing/subscriptions.

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

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

Explicitly tells when to use: to review monitoring before adding more or to find an id to cancel. Lacks explicit when-not-to-use or alternatives, 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 are all false (no destructive, idempotent, etc.). Description adds important behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against quota. 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?

Description is well-structured but somewhat verbose. Each sentence adds value (purpose, usage, constraints). Could be slightly trimmed without losing information, but still effective.

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

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

Despite no output schema, description explains what happens after submission (team reads digests, affects roadmap). Combined with rate-limit and quota info, the agent has complete context to use the tool appropriately.

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. Description adds value by explaining the type enum usage and reinforcing message limitations (1-2 sentences, 2000 chars). Not perfect because schema already provides enum values and nested object 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?

Title and description clearly state the tool sends feedback to Pipeworx team. Description explicitly mentions bug, missing features, praise. Distinguishes from sibling tools which are for queries, research, etc.

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 provides explicit when-to-use: bug, feature/data_gap, praise. Also includes what not to do (don't paste end-user prompt) and guidance to describe in terms of tools/packs.

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 significant behavioral context: data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). There is no contradiction; the description complements annotations well.

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 tightly written with no wasted words. It front-loads the core functionality, then lists use cases in a bullet-like format. Every sentence serves a clear purpose, making it easy to scan.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers all essential aspects: return content, data sources, caching, privacy, and use cases. Nothing is missing for an agent to decide to invoke it.

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 fully describes the single parameter with enum and description (coverage 100%). The description adds value by explaining the trade-off between windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enriching the parameter meaning 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 outputs 'top tools, top packs, and total call volume' for a given time window. It uses specific verbs ('returns', 'surfaces') and resource terms that distinguish it from sibling tools like discover_tools or ask_pipeworx, which serve different purposes.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use case with trends), providing clear context for when to invoke. It does not explicitly state when not to use or name alternatives, but the sibling list gives indirect 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?

Beyond the annotations (readOnly, idempotent, etc.), the description discloses key behavioral traits: Jaccard similarity threshold for cross-event pairs (≥0.30), partition filter behavior (null return if placeholder >20%), fill check against live CLOB depth, and error handling for missing args. This adds substantial context about what the tool does internally and its limitations, fully satisfying the transparency requirement.

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 structured with a clear requirement statement at the start, followed by mode explanations, internal checks, and response format. While it is somewhat long, every section adds relevant information. The front-loading of the requirement ('REQUIRES one of...') is good, but there is minor redundancy (e.g., repeating parameter guidance already in schema). Overall, it is efficient for the complexity of the tool.

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 and the absence of an output schema, the description does a commendable job explaining the response structure (opportunities array with gap_pp, suggested_trade, reasoning, etc.) and the logic behind each signal. It covers monotonicity violations, partition-sum checks, semantic anchor, partition filter, and fill check. While some details (like exact format of cross-event opportunities) are left to inference, the description is sufficiently complete for an agent to understand what the tool returns and when to trust it.

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 already covers 100% of parameters with descriptions. The tool description adds value by explaining the internal behavior of each parameter: e.g., for `event` it describes 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check.' For `topic` it explains cross-event scanning and the semantic anchor. This extra context goes beyond the schema's basic parameter description, earning a score above the baseline of 3.

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) and explains what each does. This specificity, combined with the verb+resource structure, makes it easy for the agent to understand the tool's core function and differentiate it from sibling tools like polymarket_edges or polymarket_fill_risk.

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 that one of `event` or `topic` is required and provides recommendations for each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning).' It also mentions when to use polymarket_fill_risk for custom sizing. However, it does not explicitly compare this tool to other siblings like polymarket_edges or provide clear conditions for when NOT to use this tool, which prevents a top score.

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, destructiveHint. The description adds rich behavioral context: caching at KV level for 1h, edge computation details (slippage, Kelly fractions, model families), diagnostic structure, and limitation for Fed markets. This far exceeds 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 lengthy but well-structured with enumerated model families and clear segment definitions. It is front-loaded with purpose. While verbose, every sentence adds necessary detail. Could be slightly tighter but still effective.

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

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

Despite no output schema, the description fully explains the response structure: by_segment with three categories, fed_candidates, and _diagnostics. It also covers edge fields, Kelly fractions, and filters. Caching and internal details are included. For a complex tool with 9 parameters, this is comprehensive.

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 all parameters described. The description adds value beyond schema by explaining the context for tricky parameters like 'slippage_pp' (zero fees but bid/ask spread) and 'min_partition_leg_kelly' (why min_kelly doesn't apply). This enriches parameter understanding.

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 Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'Polymarket markets', and distinguishes from siblings like 'polymarket_arbitrage' by focusing on Pipeworx disagreement. The user scenario 'what should I bet on today' further clarifies purpose.

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: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It details knobs like min_liquidity and max_spread_pp to filter tradeable edges. However, it does not explicitly mention when not to use it or compare to alternatives like '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?

The description adds behavioral context beyond the annotations (readOnlyHint, etc.): snapshots are written on cache miss, gaps mean no scan that day, history bounded by TTL, decay from daily closes not intraday. 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 but well-structured with implicit sections (ARGS, RESPONSE, LIMITS). It is front-loaded with the key question. While it could be slightly tighter, 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?

Despite no output schema, the description fully explains the response structure: tracked[], expired[], snapshot_dates[], including field meanings and edge cases like gaps and decay computation. This 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?

Both parameters are described in the schema (100% coverage), and the description adds context like defaults (days=14, window='1wk'), max for days (30), and meaning of window as snapshot family. This adds 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 provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes from siblings like polymarket_edges by focusing on time-series and decay, with specific verb+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?

The description gives context by noting that a fresh wide edge and an old wide edge are different trades, implying when to use the tool (before trading based on edge age). It mentions limits (60-day TTL) but does not explicitly name sibling tools for alternatives, though it's clear this is for historical perspective.

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, idempotentHint=true, destructiveHint=false. The description adds behavioral context: order book depth checking, verdicts (clean|degraded|cannot_fill), thin legs risk, and forced directional risk. 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 comprehensive but slightly redundant (e.g., repeats 'REQUIRES one of...'). However, it is well-structured with clear sections, front-loaded with core purpose, and every sentence adds necessary detail.

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 having no output schema, the description explains return values (top_of_book, vwap_fill_price, verdicts, etc.) thoroughly. It covers two modes, parameter constraints, and risk details, making it 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%, so baseline is 3. The description adds significant meaning: explains single-market vs basket modes for market/event parameters, side defaults and interpretations, and size_usd as spend vs target proceeds vs settlement notional. This exceeds baseline.

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 is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes with specific details, and differentiates from siblings like polymarket_arbitrage and polymarket_edges by specifying when to use it.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the risks of partial fills and directional exposure. However, lacks explicit 'do not use' scenarios.

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, but description adds critical behavioral details: safety fields, compatibility_warning scenarios, temporal alignment, and skipped leg counters. Exposes conditions where outputs are meaningless.

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 sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded key info. Slightly verbose in safety field explanations but 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 comprehensively covers response fields, data quality signals, and common failure modes. Adequately handles the high complexity of cross-venue spread calculation.

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 each param, but description adds examples, enumerates topic constants, and explains override behavior. Provides meaning 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' with specific verb+resource. It distinguishes from sibling tools like polymarket_arbitrage by focusing on inter-venue 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 describes two modes (topic shortcuts and explicit tickers) and provides guidance on when spreads are meaningful vs. when compatibility warnings fire. Warns that most pre-mapped topics are not tradeable, preventing misuse.

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

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

Annotations already cover readOnly, idempotent, non-destructive. Description adds scoping details (anonymous IP, BYO key hash, account ID) and pairing advice, adding value 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 sentences, front-loaded with purpose, no redundant info. Could be slightly tighter but effective.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. Covers purpose, scoping, and pairing with siblings.

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 100%. Description adds meaning: 'omit to list all keys' and gives usage examples, enhancing 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?

Description clearly states it retrieves a value saved via 'remember' or lists all keys if omitted. Uses specific verb+resource and distinguishes from sibling tools like '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?

Provides explicit context: look up stored information, examples (ticker, address, notes), and pairing with remember/forget. No explicit when-not, but clear use case.

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

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

The description discloses that 'mark_read:true' flags events as read, implying a state change. However, the annotations declare 'readOnlyHint:true', which contradicts this behavior. Per rubric, a score of 1 is given when description contradicts 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 well-structured with a clear front-load of purpose followed by details. It is slightly lengthy but every sentence adds value. Could be trimmed slightly, but overall efficient.

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

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

The description covers return fields, polling usage, and an alternative access method. Without an output schema, it provides enough information for an agent to understand the tool's behavior and expected results. Very complete for a retrieval tool with strong 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?

The schema covers all 5 parameters with descriptions (100% coverage). The description adds contextual value by explaining the purpose of mark_read and the filtering options, and hints at unread functionality. This is above the baseline of 3.

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 pulls fired events from a subscription feed and returns recent alerts with specific fields. It is specific about the resource and action, but does not explicitly differentiate from sibling tools like 'recent_changes' or 'list_subscriptions'.

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 filtering by type and ISO timestamp, polling behavior, and notes that the same feed is also available via a GET URL. It does not provide explicit exclusions or compare to alternatives, but the context is clear enough for typical 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?

The description adds significant behavioral detail beyond the annotations, such as fan-out to multiple sources, fallback behavior (GDELT preferred, GNews on rate-limit/5xx), soft-fail for USPTO due to API sunset, and citation URI format. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description is fully consistent with them.

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

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

The description is detailed but efficient, with front-loaded example queries to establish purpose quickly. Every sentence adds value, though it is slightly long. The structure is logical: examples, then fan-out specifics, then parameter guidance, then alternative tool reference.

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

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

Given the tool has 3 required parameters, no output schema, and moderate complexity (multiple sources, fallback), the description covers the return structure (changes grouped by source, total_changes count, citation URIs) and all key behaviors (fallback, soft-fail). It is complete enough 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?

The input schema has 100% coverage, but the description adds valuable semantics: examples for `since` (ISO date and relative shorthand like '7d', '30d', '3m', '1y'), clarification that `value` accepts ticker or CIK, and that `type` is only 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 clearly states the tool returns a change feed for a company in a recent time window, fanning out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It provides example queries like "What's new with X" and distinguishes itself from entity_profile which returns a static profile. This leaves no ambiguity about the tool's purpose.

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

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

The description explicitly tells when to use this tool ('use entity_profile instead when you want the static profile'), giving clear guidance on alternatives. It also provides example query patterns. However, it does not explicitly state when NOT to use the tool, which could be slightly clearer.

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

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

The description adds significant context beyond annotations: key-value scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. 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?

Four sentences, front-loaded with the core purpose, no wasted words, and logically ordered from what it does to when to use it to how it behaves.

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 having no output schema, the description fully explains the outcome (data stored and scoped, lifetime) and integrates well with the sibling tools and context signals.

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 provides example values (e.g., 'subject_property') but does not add new semantic information beyond what the schema already provides.

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

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

The description clearly states the verb ('Save') and the resource ('data'), and explicitly distinguishes from sibling tools recall and forget by mentioning they are for retrieving and deleting respectively.

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 guidance on when to use the tool ('when you discover something worth carrying forward') with concrete examples, and notes its relationship with recall and 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 readOnly, openWorld, and idempotent. Description adds context: cascades through endpoints, returns citation URIs, and auto-disambiguates for company.

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 front-loaded with examples and well-structured, though slightly verbose. 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?

With 2 parameters and no output schema, the description thoroughly explains inputs and expected returns for both entity types, making the tool fully understandable.

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 covers both parameters, and description adds examples and return types, clarifying how the 'type' and 'value' affect the result.

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

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

The description clearly states the tool resolves a user-spoken name to an official identifier, with multiple example queries. It distinguishes from siblings by being the go-to for name-to-ID conversion.

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 'Use FIRST whenever you have a name but need an ID.' It implies when not to use (if you already have the ID), but lacks explicit 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 already indicate readOnlyHint=true and destructiveHint=false. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns specific fields (score, confidence, signal density). 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: main action, mechanism, use case with return value. Front-loaded, no fluff, 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?

Good explanation of the comparison process and return fields. Without an output schema, the description gives enough context (ranked list with score, confidence, signal density). Could be improved by stating output format explicitly, but still adequate.

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% (all parameters have descriptions). The description adds meaning by specifying that the first entity is treated as the 'subject' for narrative and that the tool compares across entities, which is not in the schema individually.

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, using specific verbs like 'probes', 'ranks', and 'surfaces'. It distinguishes from sibling ai_visibility_check by implying 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 states usefulness for competitive AI-marketing audits and gives an example question. Provides clear context but does not mention when not to use or explicitly name 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description details partial failure behavior, timeout durations for first bundlephobia measurement, and that sources_failed will list timeouts.

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 front-loaded with purpose and each sentence adds distinct information. Could be slightly trimmed but still 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?

Despite no output schema, description thoroughly lists return fields, advisory details, links, and alternative versions. Alone it provides enough context for an agent to understand what to expect.

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

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

Schema has 100% coverage for both parameters, but description adds useful context like scoped package acceptance and default version behavior, exceeding baseline of 3.

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 'composite check in ONE call' for evaluating npm packages, specifying the exact use case. It distinguishes itself from sibling tools by focusing on npm dependency scanning.

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 examples ('is X safe / popular / small' or 'what does adding lodash cost me') and notes ecosystem limitations, directing to deps.dev directly for other ecosystems.

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, destructiveHint. The description adds context that this is full-text search across all providers, which is not captured in annotations. 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, front-loaded with purpose. Every sentence provides value: first sentence defines action and scope, second sentence specifies output format. No redundancy or 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?

Given the tool's simplicity (3 params with 100% schema coverage, rich annotations, and an output schema), the description covers the essential aspects: what it does, scope, and return format. 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?

Schema description coverage is 100%, so baseline is 3. The description does not add parameter meaning beyond the schema's descriptions (e.g., 'free-text search' matches schema). No additional semantics for parameters like limit or offset.

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

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

The description clearly states the verb 'search', the resource 'across all providers', and the output 'matching series with provider/dataset/series codes and human labels'. It differentiates from sibling tools like 'search_within' and 'find_series' by indicating global 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?

No explicit guidance on when to use this tool versus alternatives like 'search_within' or 'find_series'. The description only implies usage via 'across all providers', but no exclusions or context-specific advice.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. This goes beyond annotations and fully informs the agent.

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, each essential. First sentence states purpose, second gives usage and output features, third adds technical details. No wasted words, 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?

Despite no output schema, the description explains the output (top-N passages with char offsets and similarity scores). It covers truncation, embedding model, and pairing with another tool. Comprehensive for a search tool with 3 parameters.

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 does not add significant new meaning beyond the schema's parameter descriptions; it repeats the idea of passing a fetched record and a natural-language query, but the schema already captures this. No added semantic depth for the parameters themselves.

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

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

The description clearly states the verb 'search' and the resource 'inside a fetched record'. It distinguishes itself from siblings like 'search' (external search) and 'ask_pipeworx_grounded' by explaining its role as a semantic search over already-pulled text.

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: when the record is too large to fit in the prompt. Also describes how it pairs with 'ask_pipeworx_grounded', providing a clear workflow. No misleading 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?

The annotation idempotentHint is true, but the description states it 'Returns the new subscription id', implying a new resource is created each time, which is not idempotent. This is a direct contradiction, resulting in a low score despite other behavioral details like delivery limits and verification.

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 examples and front-loaded purpose. However, it is somewhat verbose, though every sentence adds value. Could be slightly tighter 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 complexity of 3 parameters including nested objects and no output schema, the description covers authentication, all subscription types, delivery options, limits, and side effects (e.g., webhook signing). It is comprehensive for an AI agent to correctly select and invoke the 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?

With 100% schema description coverage, the description adds extensive context beyond the schema, including concrete examples for each type-specific params, delivery channel details (email, SMS, webhook) with validation and rate limits. This significantly aids correct usage.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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 authentication requirements (Pipeworx OAuth account) and supported subscription types with examples. It implicitly guides when to use this tool (for persistent subscriptions) but does not explicitly state when not to use or suggest 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds context about the return format (category-bucketed examples with tool+argument shapes drawn from a live catalog) and explains it's a guide, not a live query. 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 well-structured. It front-loads with common user queries ('what can I ask?'), then explains functionality, arguments, and usage. While comprehensive, it 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?

Given no output schema, the description adequately describes the return: 'category-bucketed example questions ... each with the exact tool + argument shape'. It also covers the live catalog origin. This is sufficient for an agent to understand what to expect, though it could mention if results are static or dynamic.

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 optional string parameter. The description adds the exact list of topic values (e.g., 'finance', 'pharma') and clarifies that omitting the parameter returns a cross-category spread, while specifying a topic focuses the results.

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

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

The description uses specific verbs ('returns category-bucketed example questions') and clearly distinguishes the tool as the onboarding entry point. It contrasts with sibling tools by framing it as the 'first' step when the agent doesn't know what Pipeworx can do.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also provides guidance on invoking with or without the 'topic' argument, and explains the outcome of each case.

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 non-read-only, non-destructive, idempotent. The description adds vital behavioral info: 'deactivated (not deleted)' and 'historical events stay available via recent_alerts'. This 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?

The description is three sentences, front-loaded with the action. It is concise with no fluff, though slightly could be tightened. Still highly 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?

With one parameter, no output schema, the description fully explains behavior (ownership, deactivation, history availability). It fits well with siblings like 'subscribe' and 'recent_alerts'. 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?

Schema coverage is 100%, so baseline is 3. The description does not add new parameter details beyond the schema's description, but it is consistent. The parameter role is clear from the context.

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 'Cancel a subscription by id', using a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by explicitly mentioning ownership enforcement and the deactivation behavior.

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

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

The description implies when to use (having a subscription id) and notes ownership enforcement. It does not explicitly state when not to use, but the context is clear. It provides a reference to 'recent_alerts' for historical events, offering usage context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant context: it returns a verdict, extracted structured form, actual value with citation, and percent delta. It also reveals the underlying data sources (SEC EDGAR + XBRL) and version scope ('v1 supports company-financial claims'). 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 verbose but front-loaded with trigger phrases. It includes redundant examples and a note about replacing multiple calls, which could be more concise. While informative, it could be trimmed without losing meaning. Adequate but not optimal conciseness.

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

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

Given no output schema, the description explains what the tool returns (verdict, structured form, actual value, citation, delta). It covers input format, target domain, and data sources. Missing details on error handling or limitations beyond v1 scope, but sufficiently complete for a single-parameter tool with good 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?

Only one parameter 'claim' with schema description that already gives examples. The tool description provides additional example phrases in the main text, but this is additive rather than essential. With 100% schema coverage, the baseline is 3, and the description does not significantly enhance semantic understanding beyond what the schema provides.

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

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

The description explicitly states it is for 'natural-language claim verification against authoritative sources' and provides specific trigger phrases like 'Is it true that...' and 'fact check'. It clearly distinguishes this tool from siblings by focusing on company-financial claims via SEC EDGAR + XBRL.

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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the domain (company-financial claims). It also notes that the tool 'replaces 4-6 sequential calls', indicating efficiency. However, it lacks explicit when-not-to-use or alternative tools.

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