Data Bloomington

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

Annotations declare readOnly, openWorld, idempotent hints. The description adds value beyond annotations by specifying the default model (Workers AI Llama-3.3-70b, free), cost implications (Anthropic requires BYO key), and return structure (per-model {score, confidence, signals, raw_response}). 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 a single front-loaded paragraph of four sentences, each providing essential information: core action, default and optional settings, return format, and use cases. No unnecessary words or redundancy.

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

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

Despite the complexity of 4 parameters and no output schema, the description adequately outlines the return format (per-model + combined view), mentions models and key usage, and states the score range. This is sufficient for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% with all parameters described. The description adds extra context: explains that '_apiKey' is passed straight through to api.anthropic.com, that 'context' helps disambiguate, and that 'models' support 'workers-ai' and 'anthropic'. This enhances 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 specifies the verb 'probe', the resource 'LLMs for knowledge about an entity', and the output 'score visibility (0-100) per model'. It distinguishes from sibling tools like 'ask_pipeworx' and 'deep_research' by its specific AI-marketing audit focus.

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

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

The description states the tool is 'useful for AI-marketing audits, pre-launch brand checks, competitive monitoring', providing clear use cases. It also explains the default model and optional API key for Anthropic. However, it does not explicitly mention when not to use or compare with alternatives, which would strengthen 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it routes to 5,008 tools, returns stable citation URIs, and works on every tier in one fast call. No contradictions.

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

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

The description is somewhat long but well-structured: preference statement first, then usage guidance, alternatives, and examples. Every sentence adds value, but some redundancy could be trimmed.

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, sibling tools), the description covers purpose, usage, alternatives, and examples. It lacks details on output format (no output schema) and potential limits, but is adequate for the scope.

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

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

Schema coverage is 100% with clear alias descriptions. The description adds value by explaining that the question is in natural language and providing examples, which 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 the tool answers factual questions using structured data from 5,008 tools across 1318 sources. It uses specific verbs like 'routes', 'returns', and provides examples, distinguishing it from web search and sibling tools.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and gives detailed when-to-use criteria (e.g., factual questions, specific domains) and when to step up to alternatives (ask_pipeworx_grounded, deep_research). It also lists example queries.

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

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

Annotations already provide safety traits (readOnlyHint, idempotentHint, etc.). The description adds behavioral context: experimental nature, source-preference ranking, and comparison against stable router. It does not contradict annotations. However, it could elaborate more on how routing behavior changes (e.g., order of tool selection).

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

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

Three concise sentences, each adding value: identity and difference, usage instruction, and reassurance. No superfluous words.

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

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

Given the tool is a beta router with no output schema, the description references the sibling ask_pipeworx for response shape. For an agent familiar with ask_pipeworx, this is sufficient; for a new agent, it might be slightly lacking, but the universal router nature is implied.

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 merely references 'same arguments' and aliases, adding no new detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,008 tools, arguments, and response shape. It specifies the key difference: candidate routing improvements enabled live, specifically source-preference ranking. This distinguishes it from siblings ask_pipeworx and ask_pipeworx_grounded.

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 it exactly like ask_pipeworx when you want the newest routing'. Also implies when not to (for stable routing, use ask_pipeworx) and clarifies it is a full working router, not a fallback.

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

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

Annotations already declare read-only and non-destructive. Description adds specific behavioral details: hallucination-resistance, extraction from tool result, refusal reasons, and the extra LLM call cost. 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?

Well-structured and front-loaded with purpose. Every sentence adds value, though slightly verbose for the core message.

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

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

Describes return format (answer, evidence, confidence, source, etc.) despite no output schema, covers refusal cases, and differentiates from sibling tools thoroughly.

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 (including aliases). The description does not add significant meaning beyond what the schema provides, so baseline 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 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes from sibling ask_pipeworx by explaining the grounded extraction behavior and refusal mechanism.

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: 'whenever an answer will be quoted, cited, or acted on' and when to prefer ask_pipeworx: 'prefer ask_pipeworx for casual lookups' due to extra cost.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds extensive behavioral details: market resolution, classification, fan-out, response shapes, safety mechanisms (low-confidence match, closed markets, wide spread, cancellation rules), and error handling. This significantly adds 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?

The description is very long and rambling, lacking a clear structure. It mixes parameter guidance, fan-out examples, response shapes, and safety notes in a single paragraph. While detailed, it could be better organized and more concise. Every sentence earns its place, but the overall length and lack of front-loaded key info reduce effectiveness.

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 input types, data sources, error cases, and response shapes), the description is remarkably complete. It covers input semantics, behavioral details, response fields (market, analysis, evidence, resolver contract, parent event, news fields, safety notes), and edge cases. No output schema exists, so the description fully compensates.

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%, but the description elaborates on each parameter: market input can be slug, URL, or question text; depth parameter explains quick vs thorough; include_raw describes the trade-off between summarized and full payloads. This adds meaningful context 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 input types and output, and distinguishes from sibling tools like polymarket_edges by focusing on individual bet 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?

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".' While it doesn't explicitly state when not to use, the examples and context imply appropriate usage. A clear when-not-to-use would enhance this dimension.

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, destructiveHint=false, and the description adds valuable behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted results by primary metric, and citation URIs. 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 relatively long but front-loaded with natural language triggers. Every sentence adds value (examples, data details, sorting behavior, efficiency claim). Slight wordiness could be trimmed, but structure is logical.

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 mentions 'paired data + pipeworx:// citation URIs' but doesn't detail the output structure. It covers purpose, usage, and data sources well, but an agent might benefit from more explicit output format. Still, it's largely complete for effective tool invocation.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: examples for 'values' (tickers/CIKs, drug names) and clarifies what each enum option retrieves. It doesn't detail parameter syntax extensively, but provides practical 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 starts with clear natural language examples ('Compare X and Y', 'X vs Y') and explicitly states it does side-by-side comparison of 2–5 companies or drugs. It distinguishes from siblings by noting it replaces sequential single-pack lookups, which aligns with the sibling entity_profile for single entities.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear directive. It also specifies when to use (comparing 2–5 entities) and differentiates by type (company vs drug), giving context for selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and idempotency. The description adds that results are paginated (limit, offset) and returns specific fields, which is useful behavioral context beyond the annotations.

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

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

Two concise sentences, no fluff. The description is front-loaded with the core purpose and includes actionable guidance about passing resource_id. Every sentence earns its place.

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

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

Given the simple parameters (3, all optional) and no output schema, the description adequately covers what the tool does, what it returns, and what to do next. It could benefit from a brief example or note on response format, but is sufficiently complete.

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

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

All three parameters have schema descriptions, and the tool description adds context: query is a keyword search on titles/descriptions, limit has a range (1-100, default 20), and offset enables pagination. This enriches 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 action (search by keyword), the resource (Bloomington Open Data catalog), and the output fields (resource_id, name, description, category, update date). It also distinguishes from 'query/metadata' by telling the agent to pass resource_id to that tool, aiding differentiation.

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 guidance on when to use this tool (searching for datasets by keyword) and links to a related tool (query/metadata) for further detail. It does not explicitly state when not to use it, but the context and sibling tools imply its purpose.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: account requirement, non-open-web, parallel decomposition, output format (findings packet with gaps, contradictions), time expectations, and depth level behaviors. 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 dense with useful information but somewhat lengthy. It is front-loaded with critical details (account, sibling comparison), but some minor details (e.g., semantic excerpting) could be streamlined. Overall, it is informative but could be more 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 having no output schema, the description thoroughly explains the return format (findings packet with evidence, confidence, source, citation, gaps, contradictions) and behaviors like second-hop iteration. Given the tool's complexity and lack of output schema, the description is complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining each depth level's behavior (number of facets, gap recovery, contradictions scan) beyond the schema's enum labels. This helps the agent understand the impact of parameter choices.

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

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

The description clearly states that the tool performs grounded multi-source research across structured data sources, decomposing questions into facets and running parallel tool calls. It distinguishes itself from siblings like ask_pipeworx by specifying use for broad/multi-part questions and not for current news or single 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 provides when to use (broad/multi-part questions on structured data) and when not to use (breaking news, single lookups), plus alternatives (ask_pipeworx). It also mentions account requirements and paid tiers.

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

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

Annotations already declare readOnly, idempotent, non-destructive; description adds that results include names, descriptions, schemas, and are ready to call, enhancing transparency beyond annotations.

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

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

Description is concise, front-loads purpose, lists domains efficiently, explains return value in a single sentence, with 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 no output schema and complexity, description explains purpose, usage, and return format (tools with names, descriptions, schemas). Minor gap: no error handling or empty query behavior.

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

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

Schema covers all parameters (100% coverage); description adds alias information (task, q, search, description) and clarifies that query is a natural language description, going 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 the tool finds tools by describing data/task, lists specific domains, and differentiates from siblings by emphasizing discovery of available tools.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance and hinting at alternatives.

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

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

The description adds significant behavioral context beyond annotations, including data sources (SEC, XBRL, USPTO, news, GLEIF), return fields (cik, filings, fundamentals, patents, news, LEI), and failure modes (patents soft-fail). 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 dense with useful information and front-loads with examples and purpose. However, it is somewhat verbose; minor redundancy (e.g., 'names not supported' repeated) could be trimmed.

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

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

For a complex tool with no output schema, the description thoroughly covers inputs, outputs, sources, and limitations. It provides a complete picture for an agent to use effectively.

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

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

Schema coverage is 100%, but the description adds meaning by specifying that 'type' is only 'company', 'value' accepts ticker or zero-padded CIK, and names are not supported. This enriches the schema definitions.

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 as returning a 'full cross-source profile of a US public company' with multiple examples. It distinguishes from siblings by explicitly preferring over chaining single-pack lookups and referencing 'resolve_entity' for name resolution.

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 is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and names are not supported, recommending 'resolve_entity' first. This covers when to use and when not, with clear 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?

Description aligns with annotations (destructiveHint=true). Adds context about clearing sensitive data and relevance of key. No contradictions; additional behavioral context is useful 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?

Two sentences, front-loaded with action, every sentence adds value. No wasted words.

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

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

Simple tool with one parameter and clear annotations. Description covers purpose, usage, and pairing. Lacks return value details but output schema is absent so not critical.

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 describes key as 'Memory key to delete'. Description says 'by key' which adds no new meaning; 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?

Clear verb 'Delete' and resource 'memory by key' are stated. It distinguishes from siblings (remember, recall) by explicitly mentioning pairing and contrasting use case.

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 context is stale, task done, or to clear sensitive data. Mentions pairing with remember and recall, but doesn't provide 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.

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: fetches page, extracts title/description/key links, outputs markdown text. 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 that front-load purpose, then detail behavior and use cases. Every sentence adds value with no wasted words.

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

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

Complete for a 2-parameter tool with no output schema. Covers what the tool does, how it works, and output format. Annotations cover safety and side effects.

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

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

Schema description coverage is 100%, so baseline is 3. Description reinforces parameter info (URL and max_links) but does not add significant new semantics 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 generates a production-ready llms.txt file for AI crawlers, specifies the verb 'generate' and the resource, and distinguishes from sibling tools like ai_visibility_check by focusing on file generation.

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

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

Explicitly lists use cases: getting client's site indexed, drafting own project, auditing competitor. Does not specify when not to use or alternatives, but guidance is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds value by specifying exact return fields and implying inactive subscriptions excluded by default.

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 action and result, second gives usage advice. Extremely concise and front-loaded with no redundant 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?

Simple tool with one optional param and no output schema. Description adequately covers return fields and usage. Missing error or pagination details but not essential for this 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?

Parameter is fully documented in schema with description. Description does not add extra semantics beyond what schema provides, baseline 3 for high coverage.

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

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

The description clearly states the action (list) and resource (subscriptions), specifies scope (active), and lists return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit use cases: review before adding more or find id to cancel. Does not explicitly state when not to use, but context is clear given siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false, so safety is covered. The description adds value by listing the metadata fields (columns, types, row count, category, last-updated) but does not disclose additional behavioral traits beyond annotations.

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

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

The description is a single sentence that immediately states the action and resource, with no unnecessary words. All information is relevant and efficiently presented.

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 lists the specific metadata fields returned, which compensates for the lack of an output schema. For a simple tool with one parameter, it provides enough context for an agent to understand what it will receive.

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%, providing a baseline of 3. The description adds an example value ('yv82-z42g'), which clarifies the format, making it slightly more helpful.

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: 'Get a Bloomington Open Data dataset's schema + metadata... by resource_id'. It specifies the verb 'Get' and the resource (dataset metadata), and distinguishes from siblings like 'datasets' which likely lists datasets rather than getting metadata for a specific one.

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

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

The description explicitly says to use it 'by resource_id' and provides an example ID, making the usage clear. However, it does not mention when not to use it or alternatives, though given the sibling list, no direct alternative exists.

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 annotations: it mentions rate limiting (5 per day), that feedback 'directly affects roadmap', and that it's free. Annotations correctly indicate non-readonly and non-destructive. No contradictions. Minor gap: no mention of confirmation after submission, but not critical.

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

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

The description is concise (about 6 sentences) and well-structured: starts with purpose, then gives use cases, then provides formatting guidance, and ends with constraints. 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?

For a feedback tool with no output schema, the description covers all necessary aspects: purpose, when to use, how to format input, and limitations. It is complete enough for an agent to decide when to invoke it and what to provide.

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 value by elaborating on the 'type' enum values (e.g., 'data_gap = data Pipeworx does not currently expose') and by advising on message formatting (be specific, avoid user prompts, 1-2 sentences). This helps the agent use parameters correctly.

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

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

The description clearly states the tool's purpose: to send feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs like 'Tell' and nouns like 'Pipeworx team', and it distinguishes itself from sibling tools by being the only feedback mechanism.

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 outlines when to use the tool (for bugs, feature requests, praise) and provides important constraints: rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. It also advises on how to format the message, making it very actionable for an agent.

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

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

The description discloses data source ('CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h depending on window'). These details go beyond the annotations (which declare readOnly and idempotent) and add value for 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?

The description is concise (5 sentences) with a clear structure: what it returns, use cases, and technical details. Every sentence adds value, with no redundancy or fluff.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and rich annotations, the description provides complete context: return values, time windows, data source, privacy, caching, and use cases. No gaps remain for effective invocation.

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

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

The sole parameter 'window' has full schema coverage (100%) with enum values and description. The description adds functional nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which aids selection beyond the schema's basic definition.

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 ('returns') and the resource: top tools, top packs, and total call volume over recent windows (24h, 7d, 30d). It distinguishes itself from siblings by focusing on aggregate trending data, not individual queries or entity details.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming popular tools, aligning use case with agent needs). While it doesn't explicitly state when not to use, the use cases provide clear guidance for appropriate invocation.

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 extensive behavioral details: monotonicity check, partition sum check, Jaccard similarity filter, placeholder filter, fill check against CLOB depth, realizable edge calculation. 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 somewhat lengthy but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded key functionality. Every sentence adds value, though it could be slightly trimmed for agent consumption.

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

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

Despite lacking an output schema, the description fully explains the response format (opportunities[], partition_check, realizable edge) and references a sibling tool for custom sizing. It covers all crucial aspects of the tool's behavior and output.

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 nuance: acceptable event slug formats, topic as seed question, and detailed sub-behaviors (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). This goes well 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by focusing on arb detection.

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 three modes (no args, event, topic) and when to use each. It recommends 'event' for specific markets and mentions cross-event mode for broader scans. It does not explicitly state when not to use, but the guidance is clear enough for an AI agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds extensive behavioral context: the three segments with detailed model descriptions (e.g., lognormal barrier from Fred, GDELT volume ratio, partition overround with sport-specific alpha), caching at KV level for 1 hour, response structure including diagnostics, and the exclusion of Fed bets from ranking. 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 comprehensive but verbose, containing detailed model formulas and edge-case explanations. While well-structured with segment groupings and bolded field names, it could be more concise. The front-loading of purpose is good, but the length may hinder quick scanning by an AI agent.

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

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

Given the tool's complexity (9 parameters, three segments, no output schema), the description is highly complete. It explains the three segments, all parameters with usage guidance, the response top-level structure (by_segment, fed_candidates, diagnostics), and fields within each opportunity (edge_pp_net, kelly_fraction, liquidity, spread, etc.). The diagnostics section helps callers understand empty segments.

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 documents all 9 parameters clearly. The description adds value by providing real-world context for several parameters, such as explaining typical slippage (20-50bp) in slippage_pp, recommending values for min_liquidity and max_spread_pp with examples, and clarifying the role of min_partition_leg_kelly for partition arbs. This extra context justifies a 4 rather than a baseline 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly frames the tool as 'Built for "what should I bet on today"' and explains the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from sibling tools like polymarket_edge_tracker by its focus on daily scanning and opportunity discovery.

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

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

The description provides clear usage context: 'agents discover opportunities without paging hundreds of markets' and mentions caching behavior. It doesn't explicitly state when not to use the tool or compare directly with siblings like polymarket_arbitrage or polymarket_edge_tracker, but the focus on edge detection and segmented response implies appropriate use cases. The absence of explicit exclusions prevents a score of 5.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds significant behavioral details: reads snapshots, computes trend/decay, limits (60-day TTL, not intraday), and response structure. 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 dense but well-structured with clear sections (purpose, args, response fields, limits). Some redundancy but front-loaded with key 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?

No output schema, so description covers return values in detail (tracked, expired, snapshot_dates with field explanations). Also addresses limitations (TTL, intraday). Complete for a tool with 2 optional params and 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?

Schema covers both params (days, window) with descriptions. The description adds default values (14, '1wk') and clamp range for days (2-30) beyond schema, enhancing meaning.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question about edge duration. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series tracking rather than current snapshot.

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 via the example comparing fresh vs old edges, but lacks explicit guidance on when not to use or direct references to alternative tools.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds details: walking the ladder, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and basket mode behavior including thin_legs and forced_directional_risk, without contradicting 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 clear sections and front-loaded key points. It is slightly verbose but every sentence adds value; could be slightly more concise 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?

Given the complexity of two modes and no output schema, the description is exceptionally complete. It explains both modes, return fields, use cases, and risk scenarios, compensating fully for missing schema.

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

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

Schema description coverage is 100%, providing baseline 3. The description adds extra meaning: interpretation of size_usd differs in single-market vs basket, side default logic for basket, and context for each parameter.

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

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

The description clearly states the tool's purpose: realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes with specific verbs and resources, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use the tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It also warns about pitfalls like uncapturable overround and directional risk from partial fills.

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. The description adds significant detail: compatibility_warning scenarios, temporal alignment checks, skipped_cross_type counters, and the fact that the tool may return warnings rather than spreads. 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 thorough and well-structured, starting with the purpose, then detailing modes, response format, and safety fields. While lengthy, it efficiently covers complex behavior without redundancy.

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

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

Despite lacking an output schema, the description fully explains the response structure including leg prices, top spreads, and safety fields like compatibility_warning and temporal_alignment. All relevant edge cases are addressed.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining the interaction between parameters (topic vs explicit overrides) and listing the exact topic shortcuts. It also provides examples in 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: calculating the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison, and explicitly outlines two modes of operation.

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

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

The description provides clear guidance on when to use the topic mode vs explicit mode, and warns that most pre-mapped topics may not yield tradeable spreads. However, it does not explicitly state when not to use the tool or compare directly with sibling tools.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that it returns JSON, uses SoQL without leading $, and hints at a default limit of 1000 rows. Provides useful behavioral context beyond annotations.

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

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

Two sentences, no filler, front-loaded with the core purpose. Every word contributes to understanding.

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

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

Covers main purpose, parameter usage hints, and return format. Lacks details on error handling or edge cases, but adequate for a read-only query tool with no output schema.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description reiterates SoQL clause format and limit/offset, but does not add significant new 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?

Clearly states the tool runs a Socrata SoQL query on a Bloomington Open Data dataset, using resource_id, with filtering clauses, and returns JSON. Distinct from siblings like 'datasets' which list datasets.

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 what the tool does and how to use it (resource_id, SoQL clauses), but does not mention when not to use it or directly compare to alternatives. Context is clear but lacks explicit exclusions.

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

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

Adds scoping detail (by identifier) beyond annotations that already declare readOnly/idempotent/destructive hints. 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 action, no redundant words. Each sentence adds distinct 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?

No output schema but the tool is simple; description covers retrieval behavior, scoping, and pairing with remember/forget. Sufficient for an agent.

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

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

Schema coverage is 100% with clear description of the 'key' parameter. Description reinforces its optionality for listing, but adds no new semantic details.

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

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

Clearly identifies the action (retrieve a value or list keys) and the resource (previously saved memories). Distinguishes from siblings remember and forget by specifying the retrieval function.

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 concrete use cases (user's target ticker, address, research notes) and mentions omitting key to list all. Lacks explicit when-not-to-use, but context is sufficient for simple tool.

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

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

Discloses that mark_read:true flags events as read affecting future calls, which aligns with annotations (non-destructive read). Explains that polling works and the feed is also accessible via a direct URL. 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 clearly structured, front-loading purpose, then detailing features and alternatives. No fluff or redundancy.

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

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

Despite no output schema, the description specifies return fields (source, citation_uri, raw event payload). Covers all aspects: filtering, mark_read, polling, and alternative access method. Fully adequate for a tool with optional 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% with each parameter described. The description adds examples (e.g., 'sec_8k' for type, ISO timestamp for since) and clarifies mark_read behavior, adding value beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying returned fields. However, it does not explicitly distinguish this tool from sibling tools like 'recall' or 'recent_changes'.

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

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

Provides explicit guidance on filtering by type and timestamp, using mark_read for read tracking, and mentions polling compatibility. Also suggests an alternative direct URL for scripts and dashboards, helping agents decide when to use this tool.

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

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

Discloses multi-source fan-out (SEC EDGAR, GDELT/GNews, USPTO), fallback logic, PatentsView sunset status, return structure (changes[], total_changes, URIs). Annotations already indicate read-only, idempotent, non-destructive, and open-world; description adds valuable operational context without contradiction.

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

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

Single paragraph is well-organized, front-loaded with example queries, and every sentence adds value. Slightly dense but not excessive; could benefit from minor structuring but remains 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 adequately explains return format (changes grouped by source, total count, citation URIs). Covers multiple data sources, their status, and fallback. No gaps given 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 covers all 3 parameters with descriptions. Description adds meaningful extra: 'since' relative shorthand examples ('7d', '30d', '1y'), 'value' can be ticker or CIK with example, 'type' only 'company'. Increases usability 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?

Description clearly states the tool retrieves recent changes (SEC, news, patents) for a company within a time window. It uses specific verbs like 'change feed' and distinguishes from sibling tool 'entity_profile' which provides static profile.

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

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

Explicitly lists example queries that trigger this tool ('What's new with X', etc.) and provides a direct alternative: 'Use entity_profile instead when you want the static profile'. Also describes fallback behavior between GDELT and GNews.

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 show idempotentHint=true, non-destructive. Description adds valuable context: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. 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?

Three sentences, front-loaded with purpose, no redundant phrases. 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?

The tool is simple (key-value store) with no output schema. Description covers scope, persistence, pairing with siblings, and shelf-life for anonymous users.

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

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

Schema coverage is 100% with clear descriptions for key and value. Description adds example key formats (e.g., 'subject_property'), but this is marginal beyond schema.

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

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

The description clearly states it saves data for reuse, with specific examples like ticker, address, preference. It distinguishes from sibling tools recall and forget by mentioning pairing.

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

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

Explicitly advises when to use: when discovering something worth carrying forward. Mentions pairing with recall and forget for retrieval/deletion, providing 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, open-world, idempotent, and non-destructive behavior. The description adds that each call cascades through several internal endpoints, replacing 2-3 manual lookups, which provides useful internal process transparency beyond annotations.

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

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

The description is concise, front-loaded with query examples, and structured with clear sections for usage and supported types. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description fully explains return values for both entity types, including specific fields and citation URIs. It also mentions internal cascading behavior, making the tool's behavior complete and understandable in context.

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

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

The input schema covers both parameters with descriptions (100% coverage). The description adds significant value by providing examples, clarifying accepted formats (e.g., ticker, CIK, name for company; brand/generic for drug), and detailing return fields per type, which helps the agent understand parameter semantics 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 starts with concrete example queries and clearly states the tool resolves entity names to canonical identifiers. It specifies the verb 'resolve' and the resource, and distinguishes from sibling tools by noting it replaces multiple manual 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 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also outlines supported types and their outputs, but does not include explicit when-not-to-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 provide readOnlyHint, idempotentHint. Description adds that it probes each entity with ai_visibility_check internally, ranks by score, and returns a ranked list with score, confidence, signal density. This is rich behavioral context beyond annotations, with no contradictions.

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

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

The description is a single paragraph that efficiently conveys purpose, method, and output. It is front-loaded and every sentence adds value. Slight improvement could be structuring as bullet points, but it's already quite 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?

With no output schema, the description explains return values: ranked list with score, confidence, signal density per entity. It also describes the internal call. This provides complete context for an agent to understand what the tool does and returns.

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 semantic value by noting the first entity is treated as 'subject' for narrative, and context disambiguates common names. This extra context justifies a 4.

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 compares AI visibility across multiple entities, ranks by score, and surfaces most/least recognized. It uses specific verbs and resource, and distinguishes from sibling ai_visibility_check which presumably checks a single entity.

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

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

The description explicitly frames use case as competitive AI-marketing audits with an example question. It implies comparison across entities, and the sibling list includes ai_visibility_check for single checks, providing context. Could be more explicit about when not to use, but sufficient.

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 concrete behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This exceeds annotation context.

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

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

The description is front-loaded with the core purpose, then breaks down sources, usage, ecosystem scope, and behavioral notes. It is informative without being verbose, though slightly dense. Every sentence contributes meaningful 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?

Despite lacking an output schema, the description meticulously enumerates the return structure: summary fields, per-advisory details, links, and alternative versions. It also covers error handling and latency. The description is sufficiently detailed for an agent to understand inputs, outputs, and side effects.

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

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

Input schema has 100% description coverage with both parameters documented. The description adds minor supplementary info: scoped packages are accepted for the 'package' parameter and default behavior for 'version'. This provides 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?

Description clearly states the tool performs a composite check for npm package evaluation by aggregating data from deps.dev and bundlephobia. It explicitly lists the data sources and return fields, and distinguishes itself by noting the NPM ecosystem limitation and fallback for other ecosystems.

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 use cases: 'when an agent asks is X safe / popular / small or what does adding lodash cost me'. It also clarifies ecosystem scope (NPM only) and mentions a fallback path for other ecosystems, but does not explicitly list when not to use this tool.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the tool is safe and stateless. The description adds significant behavioral details: embedding model (BGE-base-en), similarity measure (cosine), chunking (500-char overlapping windows), character limit (200K chars with truncation and flagging). 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 well-structured with front-loaded main action: 'Semantic search INSIDE a fetched record.' Then details follow in a logical order. Every sentence adds value; no fluff. Length is appropriate (about 100 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?

Despite no output schema, the description explains the return: 'top-N passages with character offsets and similarity scores.' It also covers usage, limitations (200K char cap), and model details. With good annotations and schema, the description is fully complete for an agent to use the tool correctly.

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

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

Schema description coverage is 100% (all three parameters described). The description adds extra context: for 'text', it repeats the max length; for 'query', it gives natural-language examples; for 'limit', it specifies range and default. Since schema already covers basics, the description adds meaningful examples but doesn't fundamentally change understanding. Baseline 3, bumped to 4 for the examples.

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: semantic search inside a fetched record. It specifies the type of records (SEC 10-K, article, long tool result) and the output (top-N passages with character offsets and similarity scores). It also distinguishes from sibling tools like ask_pipeworx_grounded.

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 advises when to use the tool: 'Use when the record is too big to cram into the prompt' and highlights benefits (saves context, returns only relevant passages with offsets for verification). It also mentions pairing with ask_pipeworx_grounded. While no explicit when-not is given, the context is clear enough for an agent to decide.

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

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

The description discloses creation of a subscription, return of ID, OAuth requirement, and delivery channel limitations (e.g., 10 SMS/day). Annotations indicate idempotentHint true, but description implies each call creates a new subscription (non-idempotent); however, this is not a direct contradiction as description does not claim idempotency. Overall, good behavioral context.

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

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

The description is well-structured and informative, with front-loaded purpose and requirements. It is slightly lengthy but every sentence adds value; no wasted words.

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

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

Given the tool's complexity (multiple types, nested params, delivery channels) and lack of output schema, the description is remarkably complete. It covers all necessary details for correct usage.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds significant value by providing examples and explaining type-specific parameters (e.g., sec_8k items, polymarket_edge topic).

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 uses specific verbs and resources, and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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 specifies the requirement for a Pipeworx OAuth account and lists supported types and delivery channels, implying appropriate use cases. It does not explicitly state when not to use, but provides sufficient context for correct invocation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns categorized example questions and can be called with no arguments or a topic. No contradictions, but could mention return size or limitations.

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

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

The description is front-loaded with purpose and usage examples, but is somewhat verbose with multiple questions and parentheticals. Still well-structured and informative.

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 (1 optional param, no output schema), the description fully covers purpose, usage, parameters, and behavioral context. No gaps for the agent.

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

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

Schema coverage is 100% with one optional parameter described. The description enriches meaning by specifying example values (finance, pharma) and behavior when omitted, which goes beyond the schema's minimal description.

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

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

The description clearly states the tool is the onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes, distinguishing it from sibling tools like discover_tools or ask_pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on omitting topic for full spread or passing a specific topic. Implicitly differentiates from meta-tools.

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

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

Adds value beyond annotations by revealing deactivation (not deletion) and linking to recent_alerts for historical access. Consistent with destructiveHint=false and readOnlyHint=false.

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

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

Two sentences, no wasted words. Front-loaded with action, then behavioral details. 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?

Covers action, ownership, deactivation behavior, and link to related tool (recent_alerts). Missing explicit error cases or idempotency clarification, but sufficient for a simple tool with one parameter.

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 already fully describes the 'id' parameter (uuid, returned by subscribe). Description adds minimal additional meaning; baseline score applies.

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 'Cancel a subscription by id' with ownership enforcement, distinguishing it from subscribe and list_subscriptions. Specific verb and resource.

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

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

States that ownership is enforced (can only cancel own subscriptions) and that deactivation preserves history via recent_alerts. Provides clear context but doesn't explicitly contrast with alternatives like delete.

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 about the verification process, including the two paths and return values (verdict, actual value with citation, reasoning). 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 moderately lengthy but front-loaded with key trigger phrases. Every sentence adds value, covering purpose, usage, and behavior. Could be slightly more concise, but it is well-structured and informative.

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 (two verification paths, two parameters, rich return), the description fully covers what the tool does, how it processes claims, and what it returns (verdict, value, reasoning, citation). No output schema exists, but the description adequately describes return fields.

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 value by explaining that tolerance_pct overrides implied tolerance, gives usage examples, and describes default behavior. This goes 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 does natural-language claim verification against authoritative sources. It lists trigger phrases like 'fact check' and 'verify the claim that...', and distinguishes itself from siblings by describing its two processing paths (SEC EDGAR for financial claims, grounded pipeline for others) and noting it replaces 4-6 sequential calls.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It differentiates between company-financial claims and other factual claims, implying when to use which path. However, it does not explicitly state when not to use it versus specific alternatives like ask_pipeworx_grounded.

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