Data Usdot

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

The description adds behavioral context beyond annotations: it explains that the free default model is Workers AI Llama-3.3-70b, that Anthropic probing requires an API key and direct payment, and that returns include per-model scores and signals. No contradiction with annotations (all read/idempotent hints align with probing behavior).

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

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

The description is two informative sentences plus a utility sentence. It is front-loaded with the core action and output, and 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?

Despite no output schema, the description clearly specifies the return structure: per-model {score, confidence, signals, raw_response} plus combined view. It also covers all parameters, use cases, and model selection, making it complete for an agent to understand and invoke.

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 explaining the default model for 'models' parameter, the role of '_apiKey' for Anthropic, and how 'context' helps disambiguate. This goes beyond the schema descriptions.

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

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

The description uses a specific verb 'probe' and resource 'LLMs', and clearly states the output is a visibility score (0-100). It distinguishes itself from sibling tools like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on brand visibility across multiple models, not just single Q&A or competitor scanning.

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

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

The description explicitly states when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs. optional Anthropic model usage. However, it does not contrast with any specific sibling tool or provide explicit 'when not to use' guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the description does not need to repeat those. It adds value by explaining routing behavior, argument filling, and citation URI format. However, it does not discuss potential latencies or failure modes, which would be helpful.

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 densely informative. It uses a clear structure: preference statement, use cases, examples, guidance on alternatives. Every sentence adds value, though it could be slightly shortened without losing clarity.

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

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

Given the tool's complexity (routing to thousands of tools), the description covers key aspects: when to use, what it returns, and how it differs from siblings. It does not include error handling or performance characteristics, but those are less critical. Overall, it provides sufficient context for an agent to decide and invoke 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 aliases already documented. The description reinforces that the tool accepts natural language, provides examples, and explicitly lists all alias names. It adds marginal value beyond the schema by clarifying that any alias works and showing example usages.

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 routes questions to 4,482 tools across 1,129 sources, returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each, and provides many concrete examples, making the tool's purpose unmistakable.

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 'PREFER OVER WEB SEARCH' and lists specific domains (SEC filings, FDA data, etc.). It tells when to use alternatives: ask_pipeworx_grounded for 'hallucination-resistant single answer' and deep_research for 'broad/multi-part questions'. Also includes examples of queries that trigger use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the extra LLM call cost, the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), and explicit refusal reasons. This provides behavioral transparency beyond annotations, though a 5 would require even more exhaustive detail.

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

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

The description is front-loaded with the key purpose and mechanism. It is somewhat lengthy but every sentence adds value. The structure is logical: purpose, how it works, return format, usage guidelines. Minor redundancy in listing the refusal reasons could be streamlined, but overall 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 tool's complexity and the presence of annotations and a detailed schema, the description provides sufficient context: it explains when to use, how it differs from ask_pipeworx, the return format, and refusal reasons. No output schema exists, but the return format is described in text. A score of 5 would require even more context like example inputs/outputs.

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

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

With 100% schema description coverage, the schema already documents all 6 parameters and their aliases. The description mentions 'same routing as ask_pipeworx' but does not add new semantic meaning beyond the schema. Baseline score 3 is appropriate.

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

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

The description clearly states the tool's purpose as a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from its sibling 'ask_pipeworx' by specifying that it extracts answers only from tool results and provides evidence. The verb 'ask' combined with 'grounded' and the detailed explanation make the purpose unambiguous.

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

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

The description explicitly tells when to use the tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and provides a clear exclusion: 'prefer ask_pipeworx for casual lookups.' This gives the agent precise guidance on tool selection.

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

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

The description far exceeds annotations by detailing classification, fan-out logic, response shapes, resolver contract, parent event extraction, news fallback, safety mechanisms, resolution-rule risk, and more. No contradiction with annotations (all are compatible).

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 verbose (over 600 words) with extensive examples, edge cases, and internal mechanics. It front-loads the purpose but then rambles, making it harder for an agent to parse quickly.

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

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

Given the tool's complexity and lack of output schema, the description covers everything: classifiers, fan-out examples, response shapes, resolver contract, parent event, news fields, safety, and resolution rules. No gaps found.

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

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

Schema coverage is 100% so baseline is 3. The description adds significant value: explains input interpretation for market parameter, meaning of depth (quick vs thorough), and include_raw trade-offs and recommended usage.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, and lists input types (slug, URL, question text). It distinguishes from siblings like polymarket_edges by focusing on a general research capability. However, the core purpose is embedded in a very long description.

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 usage examples are given: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' But no explicit exclusions or direct comparison to alternatives like polymarket_edges, though the context of safety mechanisms implies some limitations.

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 specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of fiscal years, sorting by primary metric, and returns citation URIs. Adds rich context beyond annotations (readOnly, openWorld, idempotent).

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

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

Well-structured with example queries upfront and bullet-like details. Every sentence adds value, but could be slightly more concise. However, the level of detail is justified given tool complexity.

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

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

Covers inputs, behavior for both types, sorting, and output highlights. Without output schema, it adequately describes return format (paired data + citation URIs). Missing exact output structure, but sufficient for agent use.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds context on value formats (tickers/CIKs for company, drug names for drug) and entity type behavior, though schema already covers basics.

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 does side-by-side comparison of 2-5 companies or drugs. Uses example queries like 'X vs Y' and explicitly distinguishes from sequential single-pack lookups among sibling tools.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', indicating when to use and implicitly when not (single entity). Provides clear context for comparison tasks.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds valuable context: it searches a specific public catalog, returns specific fields, and indicates a follow-up workflow (query/metadata). 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 and result. No unnecessary words. Efficient structure.

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

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

Given no output schema, description lists returned fields. It also hints about using resource_id for subsequent queries. Parameters are fully documented in schema. Lacks mention of pagination or offset usage, but offset is in schema. Overall sufficient.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). Description confirms 'by keyword' for the query parameter but adds no 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?

Description clearly specifies the tool searches the US DOT Open Data catalog by keyword and lists returned fields (resource_id, name, description, category, update date). It is specific and distinct from siblings like 'query' or 'search_within', which are more generic.

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 usage for keyword search and hints at next step (pass resource_id to query/metadata). However, no explicit guidance on when to use this over sibling search tools or when not to use it.

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

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

Discloses key behavioral traits: grounded research, not open-web search, returns gaps[] for unanswered facets, expected 15-60s runtime, and account requirements. Aligns with annotations (readOnlyHint, openWorldHint, idempotentHint) and adds useful context beyond them.

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

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

The description is verbose with specific numbers (1129 sources, 4482 tools) that may not be essential. However, it is well-structured with clear sections and front-loads critical info about account requirements and alternatives.

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 (multi-source, parallel research) and lack of output schema, the description is comprehensive: explains the workflow, limitations, alternatives, and expected output format, enabling correct selection and 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 meaningful detail: explains the effect of depth values (quick=3, standard=5, thorough=8 facets) and recommends broad multi-part questions for the question 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 it performs grounded multi-source research across structured data sources, decomposes questions into facets, and returns a findings packet. It distinguishes from sibling tools like ask_pipeworx and provides specific use cases.

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 mentions account requirements, alternative tool for non-signed-in users (ask_pipeworx), depth options with tier restrictions, and when to prefer ask_pipeworx for breaking news or single lookups.

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, idempotentHint=true, destructiveHint=false. Description adds that results include schemas and are ready to call, which is useful 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?

Description is informative and front-loaded with purpose, but could be slightly shorter. 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?

No output schema, but description explains the return format (names, descriptions, schemas). Covers essential context for a simple discovery tool.

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

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

Schema coverage is 100% with parameter descriptions. The description adds minimal extra meaning, just reiterates that query is natural language and mentions aliases.

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 states the tool discovers tools by describing data/task, with specific examples (e.g., SEC filings, FDA drugs). It distinguishes from sibling tools by being a search/discovery tool, not a query tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set'. Provides context for when to use, but doesn't explicitly exclude 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details data sources (SEC, XBRL, USPTO, GDELT→GNews, GLEIF), specific fields returned, limitations (USPTO API sunset May 2025 soft-fail), and fallback behavior (GDELT→GNews). This provides rich behavioral context 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 a single paragraph but is front-loaded with example triggers and core purpose. Every sentence adds value, though a slightly more structured format (e.g., bullets) could improve scannability. Overall, it is concise for the complexity of the tool.

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

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

Despite having no output schema, the description thoroughly explains what is returned (CIK, filings, fundamentals, patents, news, LEI) with details like up to 5 filings with URIs and sorted fundamentals. It also covers limitations (patents soft-fail, names unsupported), making the tool's behavior fully understandable.

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

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

The input schema already covers the two parameters with descriptions, and the description adds meaningful context: explaining that 'value' accepts tickers or zero-padded CIKs, that names are not supported, and that 'type' is currently limited to 'company.' While schema coverage is 100%, the description reinforces and clarifies the intended usage.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call.' It lists specific outputs (CIK, filings, fundamentals, patents, news, LEI) and gives example triggers like 'Tell me about X' or 'company profile for Microsoft,' making the purpose unmistakable and distinct from siblings.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' providing a clear when-to-use directive. It also warns that names are not supported and suggests using 'resolve_entity first if you only have a name,' offering an alternative tool.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description reinforces this by stating 'Delete' and adds behavioral context about clearing sensitive data, but does not significantly expand 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 extremely concise with two sentences, front-loading the action and purpose, then providing usage guidance. Every sentence adds value.

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

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

Given the tool's simplicity (single parameter, no output schema), the description is complete: it explains what it does, when to use, and how it relates to siblings. No missing information.

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 the parameter 'key' described. The tool description does not add additional meaning beyond the schema's 'Memory key to delete', so baseline 3 is appropriate.

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

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

The description clearly states the action 'Delete a previously stored memory by key', specifying the verb and resource. It distinguishes itself from sibling tools like 'remember' and 'recall'.

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

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

The description explicitly provides usage context: 'Use when context is stale, the task is done, or you want to clear sensitive data' and recommends pairing with 'remember' and 'recall', offering clear guidance on when and how to use the tool.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds behavioral context: it fetches the page, extracts content, and emits standard markdown. This aligns with annotations and provides useful detail beyond them.

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

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

The description is three sentences, front-loaded with the main purpose, then details on process and output. Every sentence earns its place, 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?

For a 2-parameter tool with high schema coverage and no output schema, the description covers purpose, input, process, output format, and use cases. It is complete and leaves no significant gaps.

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

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

Schema coverage is 100%, but the description adds value: it gives an example for the url parameter and clarifies default and maximum for max_links. This aids understanding beyond the schema's descriptions.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action and resource. It explicitly calls out that it's for AI crawlers like ChatGPT, Claude, and Perplexity, which differentiates it from sibling tools like scan_competitor_ai_presence or ai_visibility_check.

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: getting a client's site indexed, drafting for own project, or auditing a competitor. While it doesn't include explicit when-not-to-use or alternative comparisons, the context is clear and sufficient given the sibling set.

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 convey readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by specifying the returned fields, default scope (active), and the effect of the include_inactive parameter, providing behavioral context beyond annotations.

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

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

The description consists of two concise, front-loaded sentences. The first states purpose and return fields, the second provides usage guidance. 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?

For a simple list tool with one optional parameter, clear annotations, and no output schema, the description adequately covers purpose, return fields, and usage context. It is fully sufficient for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% and the single parameter 'include_inactive' is already well-described in the schema. The description adds minimal extra meaning (default behavior is active only), so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'List', the resource 'subscriptions', and the scope 'caller's active'. It also enumerates the returned 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?

The description explicitly advises to use this tool to review existing subscriptions before adding more or to find an ID for cancellation, providing clear context. However, it does not mention when not to use or explicitly name alternatives, which would elevate it to a 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, indicating a safe, read-only operation. The description adds value by detailing the specific metadata returned (columns, types, row count, category, last-updated) and the data source (US DOT Open Data), which helps the agent understand the tool's behavior and output.

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 efficiently conveys the tool's purpose, scope, and a usage example. Every word is necessary, and the structure is front-loaded with the most critical information.

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

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

For a tool with one parameter and no output schema, the description adequately covers the return value by listing key metadata fields. It does not specify output format or error conditions, but given the tool's simplicity, the information provided is sufficient for effective use.

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

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

Schema coverage is 100% with the required 'resource_id' parameter clearly described in the schema as a dataset id with an example. The description repeats this example but adds no new semantic information beyond what the schema already provides. Therefore, the baseline score of 3 is appropriate.

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

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

The description explicitly states the tool retrieves schema and metadata for a US DOT Open Data dataset, listing specific fields (columns, types, row count, category, last-updated) and providing an example resource_id. It clearly distinguishes itself from sibling tools like 'datasets' (which likely lists datasets) and 'query' (which queries data).

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

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

The description clearly indicates when to use the tool (to get dataset schema and metadata) and provides a concrete example (resource_id '4zfz-amsd'). However, it does not explicitly state when not to use it or mention alternatives among sibling tools, though the purpose is clear enough for most contexts.

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 mutation (readOnlyHint=false), and description adds valuable behavioral context: rate-limited, free, not counted against tool-call quota, human-digested daily, roadmap impact. Also instructs not to paste end-user prompts.

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 with about 5 sentences, each providing essential information: purpose, use cases, rate limits, behavioral notes, and formatting guidance. No fluff.

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

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

Given the tool's simplicity (sending feedback), the description covers all necessary aspects: what to include, when to use, constraints, and behavior. No output schema needed.

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

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

Schema description coverage is 100% with detailed descriptions. The description adds guidance to describe issues in terms of Pipeworx tools/packs, but does not significantly enhance parameter understanding beyond the schema.

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

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

Clearly states the tool's purpose: sending feedback about bugs, missing features, or praise. Uses specific verbs ('tell', 'broken, missing, or needs to exist') and distinguishes from sibling tools, none of which are feedback-related.

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 when to use (bug, feature/data_gap, praise) and includes rate limits (5 per identifier per day) and quota info. Does not specify when not to use, but context is clear enough.

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

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

Annotations already declare safe read-only behavior. Description adds caching window, data source (CF analytics-engine), and privacy (no PII). 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?

Two tight paragraphs. First states output, second lists use cases and technical details. No wasted words. Front-loaded with key info.

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

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

For a simple read-only tool with one param and no output schema, the description fully explains return values, caching, and derivation. No gaps.

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

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

Schema coverage is 100% with one parameter. Description adds meaningful context: short vs long window behavior, which directly aids parameter selection.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. It uses specific verbs and resource, and distinguishes itself by focusing on trending usage, unlike siblings like 'discover_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?

Three explicit use cases are provided (discovering hot data, confirming canonical tool, alignment). No explicit when-not-to-use but context is clear. Could mention alternatives among siblings, but sufficient 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral details: how it walks child markets, checks ordering, partition check, semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholders >20%), fill check (theoretical vs realizable edge), and response structure. No contradictions.

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

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

Description is long but efficiently packed with essential information. Starts with requirement, then explains modes, semantic anchor, partition filter, response, and fill check. Each sentence adds value, though slight restructuring could improve scannability.

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

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

Given no output schema, description explains response fields (opportunities[], partition_check, fill check). Provides thresholds (3pp deviation, 0.30 Jaccard, >20% placeholder fraction) and warns about realizable edge ≤0 meaning not tradable. Comprehensive for a scanning tool.

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

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

Schema description coverage is 100% (both parameters have descriptions). Description adds further context: event recommended for specific market, topic for cross-event scanning, and explains usage patterns. Schema already covers basics, so description supplements rather than carries the burden.

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 arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies two modes (event and topic) with distinct use cases, making the purpose highly specific and differentiating it from siblings.

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 requirement: one of event or topic must be provided; call with no args fails. Recommends event for specific markets and topic for cross-event scanning, explaining what cross-event catches. Mentions fill check and when not to trade, and references sibling tool polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: 1h KV-level caching, Fed bets exclusion with reason, diagnostic fields explaining empty segments, and detailed model family logic. This far exceeds the annotation scope.

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 long but efficient, front-loaded with purpose, then structured into model families, output structure, and knobs. Every part earns its place; the detail is justified by the tool's complexity, though minor trimming could be possible.

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 9 parameters and no output schema, the description fully covers expected behavior: output segments (by_segment), diagnostics, cache setup, Fed bet handling, and per-leg details. An AI agent can understand what the tool returns and how to interpret results.

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 explaining how parameters like min_liquidity, max_spread_pp, and min_partition_leg_kelly serve as tradeable-edge knobs, and min_partition_leg_kelly specifically applies to partition overround opportunities, complementing 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, targeted at 'what should I bet on today'. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 positions the tool for discovering new trading opportunities without manual paging, and explains the tradeable-edge knobs (min_liquidity, max_spread_pp) for filtering. It does not explicitly mention when not to use it compared to siblings, but the context is clear.

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

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

The description exceeds the annotation's read-only and idempotent hints by detailing the response structure (tracked, expired, snapshot_dates), computation methodology (decay from daily closes), data freshness (snapshot TTL, gaps), and limitations. This provides substantial context beyond annotations.

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

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

The description is well-structured, front-loaded with the core purpose, and each sentence adds value. It efficiently covers intent, response format, and limitations without redundancy.

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

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

Given the complexity of the response (three arrays with detailed fields) and no output schema, the description provides complete contextual information. It explains what each field represents, how decay is computed, and data availability constraints, making the tool understandable 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?

Both parameters (days, window) are described in the input schema with complete coverage. The description restates these with minor differences (max 30 vs clamp 2-30), but adds no new meaning beyond what the schema already provides. Hence baseline score of 3.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay over time. It uses specific verbs and resources ('edge persistence and decay telemetry') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series analysis rather than current snapshots.

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 the tool (to answer questions about edge duration and shrinkage) and includes a practical example contrasting fresh vs. old edges. However, it lacks explicit guidance on when not to use it or direct comparisons with sibling tools like polymarket_edges.

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=false. The description adds detailed behavioral traits: it walks the order book ladder, returns 7+ fields per mode, and explicitly warns about thin books and directional risk. 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 structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loaded with the core purpose. Every sentence adds necessary information; there is 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 complexity (two modes, multiple parameters, no output schema), the description is complete: it explains all return fields for both modes, describes behavior, and provides risk warnings. No gaps remain.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds significant meaning: explains the mode-dependent behavior of `side` and `size_usd`, default values, clamp ranges, and the interaction between `market` and `event` parameters. 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 starts with a precise verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and explicitly contrasts with 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 provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the consequences of not using it (partial fills causing unhedged positions) and is fully actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral context: compatibility_warning conditions, temporal alignment checks, skipped cross-type/subtype counters, and response structure (raw probabilities, spread in percentage points). 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 slightly long but each sentence adds meaningful information, starting with the core purpose then detailing modes, response, and safety fields. Could be trimmed slightly, but content is well justified.

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 (3 parameters, no output schema), the description adequately covers response structure, edge cases (skipped pairs, temporal alignment), and interpretation. Minor gap: no mention of error handling or rate limits.

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

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

Schema coverage is 100% (all three parameters documented). The description adds value by listing valid topic values, explaining override behavior, and providing concrete examples. Baseline 3 + extra context justifies 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 the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and explains what the tool outputs, distinguishing it from generic comparison tools.

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

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

The description explains when to use the tool (to compare prices across venues for the same event) and when not (when compatibility_warning or temporal_alignment:false indicates no arb). It gives guidance on interpreting safety fields but does not explicitly contrast with sibling tools like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns rows as JSON, confirming the output format and reinforcing the read-only nature without contradiction.

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

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

The description is two sentences with no wasted words. It is front-loaded with the core action and resource, then provides details on filtering and output.

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 7 parameters and no output schema, the description covers the main querying concepts (SoQL clauses, pagination) and indicates JSON output. It is complete enough for an agent to understand the tool's 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%, so baseline is 3. The description adds meaning by explaining that SoQL clauses should be provided without the leading $, and gives examples for where and select, which adds value beyond the schema.

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

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

The description clearly states the verb 'Run' and the resource 'Socrata SoQL query against a US DOT Open Data dataset by resource_id'. It is specific and distinguishes from sibling tools, none of which perform similar queries.

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

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

The description explains when to use this tool: to run a SoQL query with filters and pagination. It does not explicitly state when not to use it, but the context is clear and no alternative tools are listed that overlap in function.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by explaining scoping (anonymous IP, BYO key hash, account ID) and the behavior of omitting the key (lists all keys). 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 well-structured sentences with zero waste. The main action is front-loaded ('Retrieve a value previously saved via remember'), and each sentence serves a distinct purpose: action, usage guidance, and pairing.

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

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

For a simple tool with 1 optional parameter, good annotations, and no output schema, the description fully explains what the tool does, when to use it, its scope, and how it relates to sibling tools. No gaps.

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

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

Schema coverage is 100% and describes the key parameter well. The description adds meaning by clarifying that omitting the key lists all saved keys, which is not explicit in the schema. Baseline 3, plus 1 for added context.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if key is omitted. It provides concrete examples (user's target ticker, address, research notes) and distinguishes from siblings remember and forget.

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

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

Explicitly says when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget. However, it does not explicitly state when not to use or name alternative tools for similar tasks.

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

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

Annotations declare readOnlyHint=true, but the description explains mark_read:true modifies state by flagging events as read, which is a behavioral side effect. This adds value beyond annotations but creates a minor contradiction. The description also confirms idempotency and non-destructiveness for typical use.

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

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

The description is concise, with two sentences that cover purpose, returns, filtering, mark_read, and alternative access. Every sentence adds value, and it is front-loaded with the main action.

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

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

Given no output schema, the description adequately describes return values (source, citation_uri, payload). It also mentions polling suitability and alternative access. Error handling and rate limits are not covered, but for a read-only tool, this is reasonable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by giving an example for type ('sec_8k'), explaining since as ISO timestamp, and detailing mark_read behavior. It does not mention unread_only but the schema already covers it.

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

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

The description clearly states the tool retrieves recent alerts from a subscription feed, specifying the returned fields (source, citation_uri, raw payload). It distinguishes itself from sibling tools like 'list_subscriptions' by focusing on fired events and persisted feed.

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 filtering by type and since, marking read, and polling. It also mentions an alternative HTTP endpoint. However, it does not explicitly compare with sibling tools or state 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?

Adds rich behavioral context beyond annotations: fans out to multiple sources, explains USPTO soft-fail due to API sunset, describes return structure. No contradiction with readOnlyHint as it's a read operation.

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

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

Efficiently packs many details into a few sentences, though slightly verbose with example queries at start. Front-loaded with common use cases.

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

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

Covers all aspects: sources, fallback, parameter formats, return structure, deprecation notice, and alternative tool. No output schema but return format is described.

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

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

Adds meaning beyond schema: explains since accepts ISO or relative shorthand with examples, suggests '30d' for typical monitoring, clarifies value can be ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company over a window, with concrete example queries. It distinguishes from sibling entity_profile by specifying when to use each.

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

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

Explicitly instructs to use entity_profile for static profile instead, and describes fallback behavior from GDELT to GNews under rate limits or errors.

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

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

Beyond annotations, the description adds key behavioral traits: key-value pair scoped by identifier, persistence differences between authenticated (permanent) and anonymous (24-hour) users, and pairing with recall/forget. No contradiction with annotations (idempotentHint=true is consistent with saving data).

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

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

The description is concise (three sentences) with a clear structure: main purpose first, then usage guidance, then behavioral details. 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?

Given the simple nature of the tool (key-value store) and no output schema, the description fully covers purpose, usage, behavior, and relationships to related tools. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances understanding by providing example values (e.g., subject_property, target_ticker) and clarifying storage scope (scoped by identifier). 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 function with a specific verb ('save') and resource ('data the agent will need to reuse later'). It distinguishes itself from siblings by naming recall and forget, and provides concrete examples of use cases (e.g., resolved ticker, target address).

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

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

Description explicitly tells when to use the tool ('when you discover something worth carrying forward') and how it relates to alternatives ('Pair with recall to retrieve later, forget to delete'). This provides clear context for decision-making.

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

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

Adds significant behavioral context beyond annotations: explains that each call cascades through several internal endpoints and replaces 2-3 manual lookups. For each type, details the returned fields (ticker, CIK, citation URI for companies; RxCUI, ingredient, brand for drugs). 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?

Description is concise and well-structured, using examples and bullet points for 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?

Given no output schema, the description fully details return values per type. It covers all necessary information for an agent to understand what the tool does, when to use it, and what to expect.

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

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

Schema covers 100% of parameters, but description adds value by explaining how the 'value' parameter is interpreted per type (e.g., ticker, CIK, or company name for company) and provides examples. This goes beyond the schema's generic descriptions.

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

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

The description uses specific verbs ('resolve') and resources ('name to canonical/official identifier'), with concrete examples (ticker, CIK, RxCUI). It clearly distinguishes the tool's purpose from siblings by stating 'Use FIRST whenever you have a name but need an ID.'

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 FIRST whenever you have a name but need an ID') and describes the two supported entity types with their inputs and outputs, providing clear 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?

The description adds behavioral details beyond the annotations: it probes each entity with 'ai_visibility_check', ranks by score, and surfaces most/least recognized. It also describes the return format: ranked list with score, confidence, and signal density. This does not contradict the readOnlyHint or other 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: three sentences, front-loaded with the main action. The first sentence states the purpose, the second explains the process, and the third gives a practical use case. No redundant or wasteful language.

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 (ranking multiple probes) and the absence of an output schema, the description adequately explains what the tool does and what it returns (ranked list with scores, confidence, signal density). It references the sibling tool for single-entity checks. Slightly more detail on the return format would improve completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context about the overall process (probing each entity and ranking) but does not provide additional detail for individual parameters beyond what the schema already states. It mentions the models and context parameters indirectly through the process 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 compares AI visibility across multiple entities side-by-side. It specifies the verb 'compare', the resource 'AI visibility', and the scope 'multiple entities'. It distinguishes from the sibling 'ai_visibility_check' by performing a batch comparison and ranking.

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

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

The description provides a clear use case: 'competitive AI-marketing audits' and gives an example query. It implies usage when comparing multiple entities vs. a single check via the sibling tool. However, it does not explicitly state when not to use it or list alternatives beyond the implicit single-entity check.

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 openWorldHint. The description adds beyond this: it details partial failure handling (bundlephobia timeout), sources_failed field, and the return 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 a single paragraph but packed with specific details. It could be slightly more structured, but every sentence adds value. The information density is high without fluff.

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

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

Given no output schema, the description fully explains the return data (summary block, advisories, links, alternative versions). It also covers ecosystem limitations and alternative tools, making it complete for an agent to understand what to expect.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds context: scoped packages accepted and version default behavior, which enriches understanding. However, no additional nuance beyond schema.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, leveraging deps.dev and bundlephobia. It specifies the verb 'scan', the resource 'dependency', and distinguishes from sibling tools by noting that only npm is supported and other ecosystems fall under deps.dev directly.

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 usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also states when not to use: non-npm ecosystems are handled by deps.dev:version. Partial failure behavior is described.

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=false. The description adds rich behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and offset for verification. 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?

Single paragraph with no wasted words, front-loaded with purpose, then details. Every sentence earns its place.

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

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

Despite lacking output schema, the description explains return format (passages with offsets and scores) and internal mechanics. Comprehensive for a search tool with good annotations.

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

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

Schema coverage is 100%, baseline 3. The description adds value by clarifying max chars for text, giving examples for query, and stating default for limit. This goes beyond 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 performs semantic search inside a fetched record (specific verb+resource) and distinguishes itself from siblings like ask_pipeworx_grounded by explaining its role in saving context and returning passages with offsets.

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

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

Explicitly tells when to use (when record is too big for context) and pairs with an alternative (ask_pipeworx_grounded). Also explains it saves context and returns only relevant passages.

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 a mutation operation (readOnlyHint=false) that is idempotent (idempotentHint=true). The description adds context about authentication requirements, type-specific parameters, delivery channel constraints (e.g., SMS 10/day cap, webhook auto-disable), and the return of a subscription ID. 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 purpose, then authentication, types, and delivery. While lengthy, each sentence adds necessary detail given the tool's complexity. Minor redundancy could be trimmed but overall efficient.

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

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

Despite no output schema, the description mentions the return value (subscription ID) and the one-time webhook secret. It covers constraints (OAuth required, SMS cap, webhook auto-disable), making the tool self-contained for an agent to use correctly.

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

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

The description significantly extends the input schema with detailed examples for each subscription type, required vs optional fields, and delivery channel specifics (e.g., phone verification, webhook signing). Schema coverage is 100%, but the description adds practical guidance 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 creates a proactive monitoring subscription and returns a subscription ID. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying the creation action.

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 usage context: requires Pipeworx OAuth account, not for anonymous/BYO users. It lists supported types and delivery options with constraints. However, it does not explicitly mention when not to use this tool or suggest alternative tools for one-time alerts.

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 annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by specifying that the tool returns 'category-bucketed example questions' with 'exact tool + argument shape' and is drawn from the live catalog, which goes beyond the annotations.

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

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

The description is front-loaded with common user questions and uses clear punctuation. While it is somewhat lengthy, each sentence serves a purpose: stating intent, listing categories, explaining output, and providing usage guidance. It could be slightly more concise but is well-structured.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains what the tool does, when to use it, how to use the parameter, and what type of output to expect (categorized questions with tool examples). There are no gaps.

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

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

The schema covers 100% of the single parameter with a description, but the tool's description adds significant meaning by listing possible values ('finance', 'pharma', etc.) and explaining that omitting the parameter yields a cross-category spread. This provides the agent with concrete usage 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 is the onboarding entry point for new users, providing example questions categorized by topic. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes itself from sibling tools by being the first tool to call when unsure of Pipeworx's capabilities.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides guidance on calling with or without the 'topic' argument. While it does not explicitly list when NOT to use, the context 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?

The description adds key behavioral details beyond annotations: ownership enforcement, soft-delete (deactivated not deleted), and historical event availability. 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?

Two sentences, each adding value: first states purpose, second explains constraints and behavior. 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?

For a tool with one parameter and no output schema, the description covers ownership, persistence model, and historical context. It is fully adequate for the 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?

The schema already provides 100% coverage with a description for the 'id' parameter. The description does not add extra meaning beyond what is 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 verb 'cancel' and resource 'subscription by id'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the action and constraint.

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

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

It explicitly says ownership is enforced — you can only cancel your own subscriptions, which guides appropriate use. However, it does not explicitly mention when not to use or compare to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable context: it returns a verdict, structured form, actual value with citations, and percent delta. It also mentions the data sources (SEC EDGAR + XBRL) and that it consolidates multiple steps, providing 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 (4-5 sentences) and front-loaded with trigger phrases. Every sentence adds value: purpose, scope, outputs, and efficiency gains. No redundant or fluff content.

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

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

Given the simple input schema (one param) and no output schema, the description fully covers what the tool does, what it returns, its domain limitations, and data sources. It is complete for an agent to understand and invoke 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% (single parameter 'claim' with description). The tool description adds examples and emphasizes natural-language input but does not significantly expand on the schema's description. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose as 'natural-language claim verification against authoritative sources' and provides multiple trigger phrases. It clearly distinguishes from sibling tools by specifying the supported domain (company-financial claims) and the integrated approach (replaces multiple sequential calls).

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct.' It implies scope (v1 supports company-financial claims) but does not explicitly state when not to use or compare with alternatives like deep_research or query. Still, the guidance is clear and actionable.

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