Datamuse

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it returns per-model {score, confidence, signals, raw_response} and a combined view, explains that Anthropic probing requires a personal API key and direct payment, and confirms the free default model. This adds meaningful behavioral context beyond annotations.

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

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

Two sentences, no wasted words. First sentence states core action and output format. Second sentence covers defaults and optional Anthropic probing. Information is front-loaded and well-organized.

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

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

Despite lacking an output schema, the description clearly outlines the return structure (per-model score, confidence, signals, raw_response + combined view). Covers key usage scenarios and parameter dependencies. No critical information is missing for an AI agent to correctly invoke and 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 description coverage is 100% (all 4 parameters have descriptions). Description reinforces parameter meanings: default vs. optional models, API key usage, and context disambiguation. Adds value by explaining default behavior and the relationship between `models` and `_apiKey`.

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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility per model. It uses specific verbs ('probe', 'score') and resources ('LLMs', 'visibility'), and distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring per model.

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

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

Provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Mentions default model and optional Anthropic probing, giving context on when to use. No explicit when-not-to-use or alternative tool references, but the purpose 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 indicate read-only, open-world, and idempotent behavior. The description adds that it returns structured answers with stable citation URIs, mentions the number of tools and sources, and notes it's a single fast call. No contradictions.

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

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

The description is detailed but front-loaded with the key directive. It includes examples and usage guidance, making it well-structured. Some redundancy could be trimmed, 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 complexity of routing to many sources and no output schema, the description covers when to use, how it works, and what to expect (structured answer with citations). It could elaborate on return format but is sufficient.

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

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

Schema coverage is 100% and the description does not add significant additional meaning beyond what the parameter descriptions already provide. The baseline of 3 is appropriate.

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

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

The description clearly states that the tool routes questions to authoritative structured data sources with citations. It distinguishes from siblings by mentioning 'ask_pipeworx_grounded' and 'deep_research' for 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 says 'PREFER OVER WEB SEARCH' for factual questions, provides examples of when to use, and instructs when to step up to other tools. The guideline is comprehensive and actionable.

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

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

Annotations already set readOnlyHint=true, openWorldHint=true, etc. The description adds valuable details: cost of one extra LLM call, return format with evidence/refusal reasons, and explicit refusal scenarios. 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?

Well-structured with clear sections, front-loading purpose and usage. Every sentence adds value, though slightly lengthy. Minor improvement possible in brevity.

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 complexity (6 params, no output schema), the description fully covers output format, refusal reasons, use cases, and behavioral constraints. Annotations complement the description well.

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

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

Schema coverage is 100% with descriptions for each parameter. The description mentions 'question in natural language' and lists aliases but adds no significant new meaning beyond the schema. Adequate but not enhanced.

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 as a hallucination-resistant answer mode for high-stakes reads, specifying that it extracts answers only from tool results. It differentiates from sibling tool ask_pipeworx by noting the extra LLM call and refusal reasons.

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

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

Explicit guidance on when to use (high-stakes reads, quotes, legal/medical claims) and when to prefer ask_pipeworx (casual lookups). 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?

The description extensively discloses behavioral traits beyond annotations: it explains fan-out logic, safety mechanisms (low-confidence short-circuit, closed market handling, wide spread warnings), resolution-rule risk, and response structure. It does not contradict annotations (readOnlyHint, idempotentHint, destructiveHint are all consistent).

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

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

The description is very long and contains extensive detail. While it is structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), it could be more concise. Many sentences elaborate on edge cases and internal workings, which may be more than necessary for an agent to use the tool correctly.

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

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

Given the tool's complexity (multiple data sources, classification, fan-out, safety checks) and the absence of an output schema, the description thoroughly covers response shapes, safety mechanisms, and edge cases. It provides enough context for an agent to understand what the tool returns and how to interpret it.

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

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

Schema coverage is 100% with all parameters described. The description does not add significant new meaning beyond the schema; it reiterates input types (slug, URL, question) already in schema examples. Baseline 3 is appropriate as the schema carries the semantic load.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and provides usage examples ('should I bet on X'). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on different aspects.

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

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

The description gives explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not provide explicit when-not-to-use or compare with alternatives, but the context is clear. The tool is for researching a specific bet, which is well-defined.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. Description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradictions.

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

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

Single, well-structured paragraph with front-loaded use-case phrases. Every sentence adds value, no redundancy, efficiently conveys purpose, usage, behavior, and parameter details.

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

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

Despite no output schema, description covers returns (paired data, citation URIs), edge cases (off-calendar fiscal years), and replaces 8-15 sequential lookups, making it sufficiently complete for an AI agent to 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%, so baseline 3. Description enhances semantics by explaining data sources per type and clarifying that values should be tickers/CIKs for companies and drug names for drugs, beyond 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?

Description clearly states tool performs side-by-side comparison of 2-5 companies or drugs, with specific verb 'compare' and resource 'entities'. It distinguishes from sibling tool 'entity_profile' by explicitly preferring over sequential single-pack lookups.

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

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

Provides explicit usage scenarios (e.g., 'X vs Y', 'which is bigger', 'rank these companies') and advises to prefer over sequential lookups. Implicitly differentiates from single-entity tools, but could be more explicit about when not to use.

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

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

Rich behavioral details beyond annotations: returns a findings packet with 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation', includes 'gaps[] for facets the data couldn't answer', mentions expected latency of 15-60s, and clarifies it uses only structured data (not open-web). 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 long but front-loaded with critical usage requirements (account, alternative). Every sentence adds value, but could be slightly more concise. The structure is logical, moving from prerequisites to behavior to usage examples.

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

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

For a complex tool with parallel processing, account tiers, and specific data sources, the description is complete. It covers prerequisites, expected behavior, return structure, latency, and clear alternatives. No output schema, but the description sufficiently explains the return format.

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

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

Schema covers both parameters with descriptions. The description adds value by explaining 'question' can be broad/multi-part and mapping 'depth' enum values to number of facets (quick=3, standard=5, thorough=8) and noting 'thorough' requires paid plan. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources' and contrasts it with sibling tools like ask_pipeworx. It explicitly says it decomposes questions into facets and routes to tools in parallel, distinguishing it clearly from open-web search.

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

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

Provides explicit guidance: best for 'broad/multi-part questions over structured data', not for 'single lookup' (use ask_pipeworx) or 'breaking news' (prefer ask_pipeworx). Also mentions account requirement and free/paid tiers, with a specific alternative for non-signed-in users.

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 confirm read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details beyond annotations: it explains the output format ('top-N most relevant tools with names, descriptions, and full input schemas') and notes that results are 'ready to call directly, no second schema lookup needed.' This goes above and 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 the core purpose and contains no filler. However, it is somewhat lengthy due to the list of domains and output details. Each sentence contributes value, but there is slight redundancy (e.g., repeating the alias list in the schema already). Still efficiently communicates necessary 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?

Without an output schema, the description fully explains what the tool returns (tool names, descriptions, schemas with examples) and its readiness for direct invocation. It covers the limit parameter and usage context. The description is complete for a discovery tool of moderate complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing aliases for the query parameter ('Accepts task, q, description, search as aliases'), which aids understanding. It also provides examples of usage. This justifies a score above baseline.

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

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

The description clearly states the tool's purpose: finding tools by describing data or task. It provides concrete examples of domains (SEC filings, financials, etc.) and distinguishes when to use it ('Call this FIRST when you have many tools available'). The verb 'discover' and resource 'tools' are specific and unambiguous.

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

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

The description explicitly states when to use the tool ('Use when you need to browse, search, look up, or discover what tools exist for...') and gives a strong usage hint ('Call this FIRST when you have many tools available and want to see the option set'). However, it does not explicitly mention when not to use it or provide alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral details: lists data sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), specifies return fields with examples (cik, recent_filings, fundamentals, etc.), and notes the patents API sunset. This goes well 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 a single dense paragraph that contains all necessary information. It is front-loaded with examples and key instructions. However, it could be more scannable with bullet points or shorter sentences. Still, every sentence adds value; it is not overly verbose.

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

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

With only 2 parameters and no output schema, the description thoroughly covers what the tool returns (cik, filings, fundamentals, patents, news, LEI) and includes limitations (patents soft-fail, names not supported). It provides enough context for an agent to understand the full behavior and outcomes.

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

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

Schema coverage is 100%, and the description adds meaning: explains that the 'type' parameter is limited to 'company' for now with person/place coming soon, and 'value' accepts ticker or zero-padded CIK. It reiterates that names are not supported, providing crucial 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 it provides a full cross-source profile of US public companies, with explicit examples like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes itself from siblings by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', making its 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?

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view'. It also specifies what inputs are not supported ('names not supported — use resolve_entity first') and warns about patents soft-failing. This helps the agent decide when and when not to use this tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' aligns. It adds helpful context about clearing sensitive data, but no further behavioral traits are disclosed.

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: the first states the purpose, the second provides usage guidance and sibling references. Front-loaded and no extraneous words.

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

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

Given the low complexity (one param, no output schema, clear annotations), the description fully covers what is needed for correct usage, including context and alternatives.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description adds no additional meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes from sibling tools like 'remember' (create) and 'recall' (retrieve).

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 states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall', giving clear alternatives.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) already indicate safe, read-only behavior. The description adds value by detailing the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. Output is a single text blob...' This goes beyond annotations without contradicting 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 core action. Every sentence adds value: what it does, how it works, and use cases. No redundant or vague phrases. Efficient and well-structured.

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

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

For a tool with 2 parameters, no output schema, and comprehensive annotations, the description sufficiently explains behavior, output format ('single text blob'), and use cases. It covers what the agent needs to know to invoke correctly and understand the result.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds extra context: 'Full URL of the site to summarize', 'Maximum number of link entries to include (default 25, max 50)', and clarifies that output is a markdown blob. This provides meaning beyond the raw schema, earning a score above baseline 3.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL', providing a specific verb and resource. It explains the process (fetch page, extract title/description/key links, emit standard format) and distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than visibility 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 lists explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not explicitly mention when not to use or alternatives, but the use cases are clear and practical. The absence of exclusions limits a perfect score.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is clear. The description adds valuable context about default behavior (active only) and the specific return fields.

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

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

Two concise sentences, front-loaded with purpose, followed by return fields and usage. No unnecessary 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 simple tool with one optional parameter, the description covers purpose, return fields, and usage. It is fairly complete, though could mention if there are limits or pagination.

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 parameter description in the schema is sufficient. The tool description adds no extra semantic meaning beyond the schema.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the return fields (id, type, params, etc.). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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

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

Provides explicit guidance: use to review monitoring before adding more subscriptions or to find an id to cancel. Does not explicitly mention when not to use, 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 adds behavioral context beyond annotations: it reveals rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and that feedback affects the roadmap. No contradiction with annotations.

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

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

The description is well-structured with a front-loaded purpose sentence followed by usage details, constraints, and tips. It's slightly verbose but every sentence serves a purpose. Could be tightened, but still effective.

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

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

For a feedback tool with no output schema, the description covers all necessary aspects: what the tool does, when to use it, how to format input, behavioral notes, and limitations. It is comprehensively complete.

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

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

Schema coverage is 100%, but the description adds value by clarifying the enum meanings (e.g., 'bug = something broke') and explaining the optional context object's purpose. This is slightly above the baseline of 3.

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

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

The description clearly states the verb 'tell' and resource 'Pipeworx team', specifying the purpose: report bugs, request features, or give praise. It distinguishes itself from sibling tools like 'ask_pipeworx' by being a feedback mechanism.

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

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

The description provides explicit usage scenarios (bug, feature/data_gap, praise) and a clear anti-guideline ('don't paste the end-user's prompt'). It also mentions how feedback is used and rate limits, offering comprehensive when-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. The description adds value by disclosing the data source (CF analytics-engine), no PII, caching behavior (5min-1h), and the output structure. 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?

The description is three sentences, front-loaded with the core purpose. It is efficient and readable, though the phrase 'Self-aggregating signal' is slightly jargon-heavy. 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 simple input (one optional parameter) and no output schema, the description adequately explains the return (top tools, packs, volume) and caching. No gaps are apparent.

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

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

The sole parameter 'window' has 100% schema coverage with enum and description. The description adds nuanced guidance on what each window means ('shorter windows surface what's hot right now; longer windows show steady-state demand'), enriching the schema.

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

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

The description clearly states it returns trending tools/packs and call volume on Pipeworx, with time windows. The verb 'Returns' and resource 'top tools, top packs, and total call volume' are specific, and it distinguishes from siblings like discover_tools by focusing on trend 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 lists three explicit use cases (discovering hot data, confirming canonical tool, checking alignment). While it doesn't mention when not to use or alternatives, the context is sufficient for an agent to understand appropriate scenarios.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details internal logic: partition checks, Jaccard similarity filtering, placeholder filtering, fill check against CLOB depth. It explains conditions under which trades should not be executed, adding rich behavioral context.

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

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

The description is well-structured with a clear purpose statement followed by mode explanations, algorithm details, and response format. While dense, every sentence adds necessary information, but could be slightly more concise.

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

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

Given the complexity (2 optional params, no output schema), the description covers input modes, internal logic, filtering, and fill checks. It describes the response structure partially but lacks an explicit output schema, though the textual description is sufficient for an AI 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?

The schema already has descriptions with 100% coverage, so baseline is 3. The description adds significant value by providing examples, explaining how each mode works, and detailing the partition_check and similarity logic, going 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 finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes from sibling tools by focusing on arbitrage detection, with specific modes for different 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?

The description explicitly explains when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It recommends the event mode and mentions custom sizing via polymarket_fill_risk, providing clear 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. The description adds extensive behavioral details: return fields (edge_pp_net, kelly_fraction, etc.), caching behavior (1h KV cache keyed on all knobs), explanation of Fed bets exclusion, and diagnostics for empty segments. This fully discloses the tool's behavior beyond what annotations provide.

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

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

The description is lengthy but dense with essential information. It is front-loaded with the main purpose and then systematically describes segments, knobs, and diagnostics. While not overly verbose, some redundancy or potential for bullet-point formatting could improve scannability. Overall, it earns its length without wasted sentences.

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

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

Given the complexity (9 parameters, 3 model families, tradeable-edge knobs, diagnostics) and lack of output schema, the description is remarkably complete. It covers what the tool does, how it works, the response structure (by_segment, fed_candidates, diagnostics), and explanations for why segments might be empty. 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 adds substantial value for each parameter: e.g., min_kelly explains it skips small opportunities, slippage_pp details zero fees but bid/ask depth, max_spread_pp and min_liquidity describe tradeable-edge filters, min_partition_leg_kelly clarifies why partition arbs have parent kelly=0. This significantly enriches parameter understanding.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it is built for 'what should I bet on today.' It differentiates itself from sibling tools like 'polymarket_arbitrage' by focusing on multiple model families (crypto_price, news_momentum, partition_overround, concentrated_longshot) and providing a curated discovery experience.

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 the tool is for discovering opportunities without paging through hundreds of markets and explains the three output segments (model_driven, structural_arbitrage, concentrated_longshot). It also discusses tradeable-edge knobs and Fed bets exclusion. However, it does not contrast directly with 'polymarket_arbitrage' or other siblings, nor does it explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by explaining snapshot reading behavior, response structure, trend classification, and limitations (TTL, snapshot gaps). 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?

The description is well-structured with a clear lead sentence, then response format and limitations. It is somewhat verbose but efficiently conveys all necessary information.

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

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

Given the tool has 2 parameters, no output schema, and moderate complexity, the description covers the response format (tracked, expired, snapshot_dates), trend/decay interpretation, and limitations thoroughly.

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

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

Schema coverage is 100% and descriptions are provided, so the description's additional context on days and window (e.g., snapshot family) adds marginal value but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering specific questions about edge age and shrinkage. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical analysis.

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

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

The description implies usage for analyzing historical edge behavior but does not explicitly state when to use this tool versus alternatives like polymarket_edges or polymarket_arbitrage. No clear 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 (readOnlyHint, idempotentHint) are consistent. Description adds rich behavioral detail: walks order book ladder, returns top_of_book, VWAP fill, slippage, verdict, per-leg details, forced directional risk – all beyond what annotations provide.

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

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

Well-structured with sections for requirements, single-market, basket, and usage advice. Dense but every sentence adds value. No redundancy despite length, appropriate for 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?

Without output schema, description fully enumerates return fields for both modes, explains verdict logic, and warns about thin books and directional risk – complete for informed tool 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?

100% schema description coverage, but description adds significant value: explains side defaults and basket auto-logic, differentiates size_usd interpretation between single-market and basket, clarifies event vs market usage, and notes clamp range.

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 checks realizable-vs-theoretical edge against live CLOB depth, distinguishes single-market vs basket modes, and lists specific return fields. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by being the risk-check prerequisite.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', provides reasoning about partial fills and unhedged directional risk, and implies when not to use it (thin books).

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?

Disclosures beyond annotations include compatibility_warning conditions, temporal alignment checks, skipped cross types, and the fact that most pre-mapped topics are not tradeable. Annotations (readOnlyHint, etc.) are consistent and description adds rich behavioral context.

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

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

The description is fairly long but well-structured with clear sections (purpose, modes, response, safety fields). Every sentence contributes unique information, though some redundancy could be trimmed.

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

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

Given no output schema, the description thoroughly explains the response structure (leg prices, top spreads, safety fields) and all edge cases (incompatible bets, temporal misalignment). Complete for a tool of this complexity.

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

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

Schema covers all three parameters with descriptions; the description adds value by listing all topic values, explaining override behavior, and clarifying that parameters are optional. Slightly redundant with schema but adds 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 states the tool computes cross-venue spreads between Kalshi and Polymarket for the same question, with two modes, which is specific and distinguishes it from siblings like polymarket_arbitrage (likely single-venue).

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

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

Explicitly describes two modes (topic shortcuts and explicit pairs), warns that pre-mapped topics often return compatibility warnings, and explains when spreads are meaningful vs. when to expect warnings, guiding appropriate 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 and idempotentHint=true, and the description adds useful behavioral context about scoping to identifier and listing keys, 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 concise at three sentences, front-loaded with the primary action, and 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?

The description is nearly complete for a simple tool with good annotations and schema coverage, though it lacks explicit mention of the return format (value or key list).

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

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

The single 'key' parameter is fully described in schema (100% coverage), and the description adds meaning by explaining that omitting it lists all keys, which goes beyond the schema's basic 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 retrieves values saved via 'remember' or lists all saved keys when the argument is omitted, distinguishing it from sibling tools like 'remember' and 'forget'.

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

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

The description provides explicit context for when to use the tool (look up stored context like tickers or notes) and mentions pairing with 'remember' and 'forget', but does not specify when not to use it or alternative tools.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: mark_read:true causes events to be flagged read, affecting subsequent calls. It also mentions the same feed is available via a URL, which is useful for choosing the right tool.

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 four sentences, front-loaded with the core purpose. Every sentence adds value: purpose, return fields, filtering, side effect, and alternative access. 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 there is no output schema, the description adequately explains return values (source, citation_uri, raw payload). It covers all 5 parameters, side effects, and alternative access. The description is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the parameter descriptions in the schema are already present. The description goes beyond by providing an example for the 'type' parameter ('sec_8k') and explaining the side effect of 'mark_read' on future calls. This adds meaning beyond the schema.

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

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

The description uses a specific verb ('pull') and resource ('events from your subscription feed'), clearly stating the tool's purpose. It also enumerates return fields (source, citation_uri, raw payload) and filtering options, distinguishing it from siblings like 'list_subscriptions' or 'recent_changes'.

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

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

The description explains when to use the tool (e.g., polling works fine) and mentions an alternative access method (GET registry.pipeworx.io/alerts.json). It does not explicitly state when not to use it, but the context is sufficient for an agent to decide.

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

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

The description adds substantial behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.), detailing the fan-out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), the fallback mechanism, soft-fail for patents, return structure (changes[], total_changes, citation URIs), and parameter format details. This far exceeds the annotation coverage.

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, well-structured paragraph that front-loads example queries, then explains the tool's mechanism, parameters, and return format. Every sentence adds value, and there is no redundancy or wasted words.

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

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

Given the complexity of the tool (multiple data sources, fallback, parameter formats, and no output schema), the description covers all essential aspects: it explains the parallel fan-out, fallback behavior, parameter flexibility, return structure, and provides a clear alternative for static data. It is fully self-contained and leaves no critical 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?

Despite 100% schema description coverage, the description adds significant meaning to each parameter: it explains that `since` accepts ISO dates or relative shorthands with examples, that `value` can be a ticker or CIK with examples, and that `type` is currently limited to 'company'. This enriches the semantic understanding beyond the schema.

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

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

The description clearly states the tool's purpose as a change feed for a company over a specified time window, with example queries that illustrate usage. It explicitly distinguishes itself from the sibling tool 'entity_profile' by describing when to use that instead, providing excellent purpose clarity.

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

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

The description provides clear context for when to use the tool, including example queries and a specific alternative (entity_profile) for static profiles. However, it does not explicitly list all scenarios where the tool should not be used, nor does it provide exhaustive guidance on sibling differentiation beyond the single alternative.

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

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

Discloses scoping by identifier, persistence duration (24 hours for anonymous, persistent for authenticated), and the idempotent nature, adding context beyond annotations. 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?

Five sentences with front-loaded purpose. Each sentence provides essential information without redundancy. Efficient and well-structured.

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

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

With no output schema, the description adequately explains storage behavior, scoping, and retention. Covers use case, lifecycle, and related tools, making it complete 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?

Input schema has 100% coverage with detailed descriptions including examples. The tool description does not add significant meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, with specific verb 'Save' and resource 'data' as key-value pairs. It distinguishes from sibling tools recall and forget, avoiding tautology.

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

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

Provides explicit when-to-use guidance (discover something worth carrying forward) with examples. Mentions pairing with recall and forget for retrieval/deletion, and differentiates behavior based on authentication status.

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

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

Annotations already indicate safe, idempotent, read-only behavior. The description adds that it cascades through multiple lookup endpoints, which is a key behavioral trait beyond annotations. No contradictions.

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

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

The description is a single paragraph but is dense and well-organized. It starts with typical user queries, then core purpose, then supported types. Could be slightly more structured with bullet points for types, but it's efficient and front-loaded.

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

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

Despite no output schema, the description fully explains return values for both entity types, including URI citations. Given the tool's complexity (multiple internal lookups, two types), this is thoroughly complete 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 both parameters described. The description adds significant semantic value by detailing what each type returns (e.g., for company: ticker, CIK, company_name, URI; for drug: RxCUI, ingredient, brand, URI) and clarifying input formats (ticker, CIK, or name for company; brand or generic for drug).

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples like ticker, CIK, and RxCUI. It differentiates from siblings by advising '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 tells when to use ('use first'), but doesn't explicitly state when not to use or list alternatives. However, the context from sibling names and the description's 'replaces 2-3 manual lookups' implies it's a primary resolver.

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, openWorldHint=true. The description adds that it calls ai_visibility_check, ranks results, and returns specific fields (score, confidence, signal density). 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 two sentences plus a brief usage example, with no wasted words. It is front-loaded with the core purpose and includes a practical example.

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-entity comparison, calling another tool, ranking), the description covers the process and output structure. It mentions the output fields and the underlying tool. Missing details like entity count limits, but overall sufficient for an agent.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds context that the first entity in the array is treated as the 'subject' for narrative purposes, which is not in the schema. This adds value beyond the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces best/worst. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic compare).

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 it's useful for competitive AI-marketing audits and gives an example question, providing clear context. It implicitly distinguishes from the single-entity ai_visibility_check, but does not explicitly state when not to use it.

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

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

Annotations already declare it as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This helps the agent anticipate delays and handle errors.

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

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

The description is a single paragraph that is effective but slightly dense. It front-loads the core purpose and then provides details. Could be more structured with bullet points, but 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 adequately explains the return value: a summary block with specific fields, per-advisory detail, links, and recent alternative versions. Also covers timing behaviors and ecosystem limitations. The only minor gap is lack of example structure for per-advisory details, but 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 coverage is 100%, but the description adds meaning beyond the schema: scoped packages (e.g., '@types/node') are accepted, and version defaults to latest when omitted. This clarifies edge cases not obvious from the schema alone.

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

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

The description clearly states it is a composite check for npm packages, specifying the exact resources checked (deps.dev and bundlephobia) and the exact question it answers. It distinguishes well from sibling tools, none of which perform dependency scanning.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of adding an npm package. Also provides guidance on limitations (NPM only in v1) and alternatives for other ecosystems, preventing misuse.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag. These go beyond annotations.

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

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

Description is concise (4 sentences) and front-loaded with purpose. Each sentence adds value without redundancy. 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 no output schema, the description explains return format (passages with offsets and scores) and behavior (truncation flag, embeddings). Annotations cover safety. Complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions. The description adds examples for query, clarifies limit default and range, and explains the algorithm context (overlapping windows). Adds value beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record. It specifies the verb 'search within', the resource 'a fetched record', and distinguishes from siblings like ask_pipeworx_grounded. Examples (SEC 10-K, article) clarify scope.

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

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

The description explains when to use: 'when the record is too big to cram into the prompt', and what it achieves: saves context, returns only relevant passages. It also suggests pairing with ask_pipeworx_grounded. While no explicit when-not, the context is clear.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds details: returns subscription id, delivery channels, SMS cap, webhook signing, auto-disable. No contradictions with annotations.

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

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

Description is front-loaded with purpose. Well-organized with type details and delivery channels. Somewhat long but effective; each sentence adds value. Could be slightly more concise.

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

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

Given complexity (3 params, nested objects, multiple types, delivery options), the description covers most aspects. No output schema, but description states returns id. Complete enough 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%, but description adds extensive examples for each type and delivery options, including constraints like phone verification, SMS limit, webhook signing. Adds significant 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?

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' The verb 'Create' and resource 'subscription' are explicit, and the output is specified. It distinguishes itself from siblings like list_subscriptions and unsubscribe.

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

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

Provides context on when to use: requires Pipeworx OAuth account (not anonymous/BYO). Lists supported types with examples. Does not explicitly state when not to use, but gives enough differentiation. Slightly lacking in alternative 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. The description adds context about the return structure (category-bucketed example questions) and the optional topic parameter, but does not contradict annotations.

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

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

The description is front-loaded with common user queries and provides a clear structure. While slightly long, every sentence adds value, and it avoids redundancy.

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

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

Given the tool's purpose as an onboarding entry point, the description fully explains what the tool returns, how to use it with or without arguments, and its role relative to other tools. No output schema is needed as the description covers the return value adequately.

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

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

Schema coverage is 100% with a clear description of the topic parameter. The description adds value by listing possible values ('finance', 'pharma', etc.) and explaining the effect of omission, going 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 returns category-bucketed example questions with exact tool+argument shapes. It uses specific verbs ('Returns', 'Call') and distinguishes from sibling tools like 'ask_pipeworx' and '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?

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also provides alternatives like passing 'topic' for focus.

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 key behaviors beyond annotations: 'deactivated (not deleted)' aligns with destructiveHint=false, and ownership enforcement provides important context. No contradictions.

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

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

Two sentences, front-loaded with action, no wasted words. Efficiently conveys all 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?

Complete for a simple tool with one required param and no output schema. Covers action, ownership, and side effect (deactivation).

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 single parameter 'id' well described. Description provides minimal extra value by noting id comes from 'subscribe', which is helpful but not essential.

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

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

Clear action verb 'cancel' with resource 'subscription by id'. Distinguishes from siblings like subscribe and list_subscriptions by specifying deactivation vs deletion and ownership enforcement.

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 ownership enforcement ('you can only cancel your own subscriptions'), giving a clear condition for use. Lacks explicit alternatives or when-not-to-use, but the context is sufficient.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds value by detailing return values (verdict, structured form, actual value, citation, percent delta) and data sources (SEC EDGAR + XBRL), 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 example triggers, then states purpose, scope, returns, and benefits. Every sentence is informative with no redundancy. Approximately 6 sentences with zero waste.

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

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

Despite no output schema, the description covers return values and data sources adequately for a single-parameter tool. It does not address error handling or edge cases, but the scope and behavior are well explained.

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 only parameter 'claim' has a schema description with examples. The tool description reinforces this with additional examples and context, enhancing understanding. Given 100% schema coverage, the baseline is 3, but the description adds meaningful usage patterns.

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 verifies natural-language claims against authoritative sources, with specific domain (company-financial) and examples. However, it does not explicitly distinguish from siblings like 'ask_pipeworx_grounded', so it falls short of a 5.

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

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

The description provides clear context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It specifies scope (company-financial claims) but does not explicitly state when not to use or name alternative tools.

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