Statfin Fi

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, which aligns with the non-destructive, read-only nature. The description adds valuable behavioral context: it specifies default model (Workers AI Llama-3.3-70b), the optional pay-per-use Anthropic probing via _apiKey, and the return structure (per-model scores, confidence, signals, raw_response plus combined view). 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: first covers core action and scoring, second provides model details, key condition, return structure, and use cases. No wasted words; every sentence adds 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?

Given comprehensive annotations and 100% schema coverage, the description is largely complete. It explains purpose, behavior, parameters, and use cases. Although there is no output schema, the description mentions the return fields (score, confidence, signals, raw_response, combined view), which suffices. Minor gaps: does not explicitly state that the tool is idempotent (but annotations cover that) or that results may vary per model.

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

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

Schema has 100% description coverage on all 4 parameters. The description adds meaning beyond schema: explains the default model, why _apiKey is needed (BYO key, user pays), and that 'context' helps disambiguate common names. It also notes the default value for 'models' (omit for just workers-ai).

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 an entity and scores visibility (0-100). It distinguishes from siblings like 'scan_competitor_ai_presence' and 'compare_entities' by focusing on visibility scoring and mentioning specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring).

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 states use cases and provides context on when to use (AI-marketing audits, etc.). It mentions the default model and the optional BYO key condition for Anthropic, warning that the user pays directly. However, it does not explicitly exclude when not to use or list alternatives beyond the sibling tools.

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

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

Annotations mark it as read-only, idempotent, and non-destructive. The description adds rich behavioral details: it routes to one of 3,804 tools across 907 sources, returns structured answers with stable pipeworx:// citation URIs, and handles a wide range of query types. 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 efficiently structured: it front-loads the most critical advice (preference over web search), then enumerates domains and example queries. Every sentence adds value; no fluff.

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

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

Given no output schema, the description explains the return format (structured answer with citations). It covers a vast range of use cases and provides sufficient context for an agent to decide when to invoke this tool, even compared to 32 sibling tools.

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

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

The input schema has 6 parameters all aliases for 'question' with 100% coverage. The description goes beyond schema by providing multiple example queries that demonstrate how to use the parameter, adding practical semantic 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 answers to factual questions from authoritative structured data sources. It lists many domains and distinguishes itself from web search with a strong preference statement, making the purpose specific and actionable.

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' and provides examples of when to use (factual queries, specific phrases like 'what is', 'look up'). It also hints at alternatives by contrasting with web search, guiding the agent effectively.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: extra LLM call, extraction-only from tool result, explicit refusal reasons. No contradiction.

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

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

Well-structured with purpose, mechanism, return format, usage guidance, and cost trade-off. Every sentence is informative and concise.

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

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

Despite no output schema, the description fully documents the return structure and refusal reasons. Complete enough for an agent to understand behavior and side effects.

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

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

Schema has 6 aliases for 'question' with 100% coverage. Description adds no additional meaning beyond what the schema already provides for parameters.

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 hallucination-resistant mode for high-stakes reads, extracting answers only from tool results. It explicitly differentiates from sibling ask_pipeworx by noting cost and 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?

Provides explicit when-to-use: 'whenever an answer will be quoted, cited, or acted on' and when-not-to: 'prefer ask_pipeworx for casual lookups.' Also lists high-stakes domains like financial verdicts.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds extensive behavioral context: classification fan-out patterns, response shapes, resolver confidence with blocking, closed market handling, wide spread detection, cancellation rule parsing, and news fallback mechanisms. This goes far 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 lengthy but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). Every sentence provides necessary detail for a complex tool. It is front-loaded with the core purpose. Could be slightly more concise, but the structure makes it scannable.

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 classifiers, fan-outs, response shapes) and absence of an output schema, the description is remarkably thorough. It covers return value shapes, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and provides examples. No critical 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 good descriptions. The description adds clarity by explaining that 'market' accepts slug, URL, or question text, and elaborates on 'depth' and 'include_raw' behavior. While helpful, the schema already provides adequate definitions; the description adds moderate value.

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 researches Polymarket bets by pulling Pipeworx data. It specifies the verb 'research' and resource 'Polymarket bet', and differentiates from siblings like polymarket_arbitrage by focusing on evidence packets and market-vs-model comparison.

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

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

The description gives explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and mentions when analysis is suppressed (low-confidence matches, closed markets). However, it lacks explicit when-not-to-use or direct alternatives, though contextual clues are present.

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 nondestructive nature. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs, going well 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 relatively long but each sentence adds value; it front-loads example triggers and usage guidance, though some redundancy (e.g., 'side-by-side comparison' and 'replaces 8–15 sequential lookups') could be trimmed.

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

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

For a tool with no output schema, the description thoroughly explains return format (paired data + citation URIs), covers both entity types with specific metrics, and mentions sorting behavior, making it fully self-contained and actionable.

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 (type and values) with 100% coverage. Description adds meaning by explaining that values accept tickers/CIKs for companies and drug names for drugs, and clarifies the max/min constraints, which is helpful but not fully novel 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 verb 'compare' with resource 'entities' (companies or drugs) and provides numerous natural-language triggers ('X vs Y', 'rank these companies'), distinguishing it from sibling tools like entity_profile.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving strong when-to-use guidance with examples, and implies alternative (sequential lookups) without naming a specific sibling.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds expected runtime (15-60s), account/plan requirements, and output structure details (evidence, gaps). 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?

Description is fairly long but well-structured: starts with core purpose, then details, usage guidelines, requirements. Every sentence adds value; minor tautology 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?

No output schema exists, so description must explain return values—it does: structured findings packet with fields like verbatim evidence, confidence, source, citation, gaps. Also covers decomposition, parallel execution, timing, prerequisites. Very complete.

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

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

Schema coverage is 100% with descriptions. Description adds practical context: for 'question' explains broad/multi-part fine; for 'depth' explains meaning of each enum value (quick=3, standard=5, thorough=8). 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 does grounded multi-source research by decomposing questions into sub-questions, routing them to 3,804 tools across 907 sources in parallel, and returning a structured packet with evidence, confidence, gaps, etc. It distinguishes itself from sibling tools like ask_pipeworx.

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

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

Explicitly states 'Use for broad or multi-part questions' and contrasts with 'use ask_pipeworx for single lookups'. Also mentions account requirements and that depth:'thorough' requires a paid plan.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by specifying that results include full input schemas with curated examples and are ready to call directly, no second schema lookup. 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 concise with three sentences, front-loading the purpose and usage. It efficiently conveys key information without unnecessary detail, earning a 4.

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 6 parameters (1 required) and no output schema, the description explains the return structure (names, descriptions, full schemas with examples) and that results are callable. Adequate for a discovery tool, though error handling is omitted.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add new meaning beyond what the schema already provides (e.g., aliases are documented in schema). No additional semantic guidance.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous domains and explains that it returns relevant tools with full schemas, distinguishing it from sibling tools that search data rather than tools themselves.

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 instructs when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available.' It provides clear context but does not explicitly exclude alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant behavioral context: it fans out across multiple sources in one parallel call, returns specific fields (CIK, filings with URIs, fundamentals sorted, patents with sunset note, news fallback, LEI), and notes that patents 'soft-fails until reactivated'. 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, starting with concrete examples, then stating when to prefer, followed by a detailed list of what it fans out and returns. Every sentence adds value; no wasted words. It is appropriately sized 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 no output schema, the description thoroughly documents all return fields (CIK, company_name, recent_filings with URIs, fundamentals with specific fields and sorting, patents with sunset note, news fallback, LEI). It covers edge cases (patent soft-fail, name resolution prerequisite). Given the tool's complexity, the description is complete and actionable.

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 rich context beyond the schema: it explains that 'type' is only 'company' currently with future plans, and 'value' must be ticker or CIK (zero-padded) and clarifies that names are not supported, directing to resolve_entity. This provides practical guidance for correct parameter usage.

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

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

The description begins with multiple concrete examples of user queries ('Tell me about X', 'research Acme'), clearly stating it provides a 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes itself from sibling tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'. The verb is specific ('profile'), and the resource is well-defined.

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 when-to-use guidance: 'ALWAYS PREFER ... when the user asks for a holistic view'. It also states exclusions: 'names not supported (use resolve_entity first if you only have a name)'. It provides input examples and specifies accepted types (ticker or zero-padded CIK) with clear alternatives.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data, which is useful, but doesn't disclose additional behavioral traits beyond annotations.

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

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

Two sentences: first defines purpose, second gives usage guidelines. No wasted words, information is front-loaded and easy to parse.

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

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

For a simple tool with one parameter, no output schema, and good annotations, the description fully covers the necessary context: purpose, when to use, and relationship with siblings.

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

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

Schema coverage is 100% with a clear description for 'key'. The description adds no extra parameter semantics beyond what's in the schema, meeting the baseline for high coverage.

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

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

The description clearly states the action (Delete), the resource (memory), and the means (by key). It distinguishes itself from sibling tools 'remember' and 'recall' by mentioning pairing.

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

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

Provides explicit when-to-use scenarios: stale context, task done, or clearing sensitive data. Also advises pairing with remember and recall, guiding the agent on suitable 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the tool fetches pages, extracts content, and outputs a text blob, reinforcing non-destructive behavior. Beyond annotations, it provides moderate additional context about the process but does not disclose potential rate limits or large page handling.

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 bullet list, tightly packed with essential information. It front-loads the core purpose, then adds process details, output format, and usage scenarios. Every sentence earns its place, and there is no verbosity.

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

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

Despite no output schema, the description fully explains the output format (standard llms.txt markdown, single text blob) and the extraction process (title, description, key links). Given the tool's low complexity, the description is complete, covering purpose, process, output, and use cases without 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 both parameters having descriptions. The description does not add new semantic meaning beyond what the schema provides; it merely restates the url as 'any URL' and implies max_links through 'key links'. Baseline 3 is appropriate as the schema already documents parameters adequately.

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 'generate', the resource 'llms.txt file', and the scope 'for any URL'. It lists extracted elements (title, description, key links) and output format, making the purpose unmistakable. It distinguishes itself from siblings by focusing specifically on generating a standard llms.txt file, whereas siblings like 'scan_competitor_ai_presence' likely analyze broader AI visibility.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, and auditing a competitor. This gives clear context when to use the tool. However, it does not provide when-not-to-use guidance or explicitly contrast with sibling tools, which would strengthen the score.

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

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

Annotations already indicate a safe read operation. The description adds value by listing the return fields (id, type, params, etc.) and clarifying that only active subscriptions are returned by default. 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 concise sentences that front-load the purpose, then list return fields, then give usage advice. No unnecessary words.

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

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

For a simple list tool with one optional parameter and full annotations, the description covers purpose, return data, and usage context. It could mention potential pagination, but overall it's 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% (the only parameter include_inactive has a description). The description does not add further 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 'List the caller's active subscriptions', specifying the verb (list), resource (subscriptions), and scope (caller's active). This distinguishes 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 provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool and how it relates to other subscription actions.

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 write operation but not destructive. The description adds value by disclosing rate limits (5 per identifier per day) and that it doesn't count against tool-call quota, which are critical behavioral traits 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 front-loaded with purpose and then provides detailed guidance. It is somewhat verbose but every sentence adds value. Minor redundancy (e.g., 'rate-limited to 5 per identifier per day' could be condensed).

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 3-parameter tool with no output schema, the description covers all necessary aspects: purpose, when to use, formatting instructions, constraints, and rate limits. It is fully adequate for an 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 the schema already documents parameters well. The description adds context about how to construct the feedback (e.g., 'Describe the issue in terms of Pipeworx tools/packs'), which is helpful but not essential given the schema clarity.

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 for sending feedback to Pipeworx about bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools, none of which serve a feedback purpose.

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

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

Explicitly states when to use (bug, feature, data_gap, praise) and gives negative guidance (don't paste end-user prompt). Also mentions rate limits and that it's free, helping the agent decide when to invoke.

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

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

Annotations already provide readOnly, idempotent, non-destructive hints. Description adds details on data source (CF analytics-engine), no PII, and caching durations (5min-1h). No contradictions.

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

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

Three sentences plus bulleted list. Front-loaded with main function. Every sentence adds value. No 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?

Covers input (window semantics) and output structure (types of data returned). No output schema, but description adequately describes return fields (top tools, top packs, total call volume). Could be slightly more specific about format (e.g., sorted lists? counts?).

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 enum descriptions. Description adds semantic value: shorter windows for hot topics, longer windows for steady-state demand. Justifies the meaning of each window choice.

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?

Explicitly states it returns top tools, top packs, and total call volume over a window. Clear verb (returns) and resource (Pipeworx trending). Distinguishes from siblings like 'discover_tools' by focusing on call volume trends.

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?

Lists three specific use cases (hot data discovery, canonical tool confirmation, alignment check). Mentions caching behavior. Does not explicitly state when not to use, but context is clear from use cases.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds extensive behavioral details: similarity thresholds, placeholder filtering, fill checks against live CLOB depth, and trade signals. 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 densely packed with information about both modes, filler checks, similarity thresholds, etc. It is front-loaded with the requirement but could be slightly more concise. Still well-organized and logically 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 complexity (two modes, multiple checks, output without schema), the description covers return values, edge cases (no args, low similarity, placeholders), and references a related tool. It provides a complete picture 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% with descriptions. The tool description adds significant meaning: for 'event' it gives slug examples and behavior; for 'topic' it explains cross-event scanning and provides seed question examples. It also clarifies the no-args failure condition.

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 via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples, and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly says which parameter to use for single-event vs cross-event scanning, and warns that calling with no args fails. It provides conditions for when not to trade (fill check failure) but does not explicitly guide against using this tool versus siblings in ambiguous cases.

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 and idempotent. The description adds extensive behavioral details: caching behavior, model families, edge computation, diagnostic output, and filtering knobs. 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 well-structured with sections but is excessively long with detailed model formulas that could be summarized. It front-loads the purpose but includes extraneous detail. Conciseness is moderate.

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 9 parameters and no output schema, the description is remarkably complete: it details the response structure, edge calculation, filtering effects, caching, and diagnostics. The agent can fully understand behavior and output without additional documentation.

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

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

All parameters are already well-documented in the input schema with 100% coverage. The description mentions some knobs with extra context (e.g., 'drops opportunities where edge isn't realizable'), but these are largely redundant. Thus, moderate added value.

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. It specifies three model families and includes a use case ('what should I bet on today'), making the purpose very clear and actionable.

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 (daily betting discovery) and explains many behavioral details, but does not explicitly mention when to avoid or compare with sibling tools like polymarket_arbitrage. It hints at limitations (Fed bets unreliable) but lacks full 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 the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral context: it describes the response structure, how snapshots are generated (on cache-miss), that decay numbers are from daily closes (not intraday), and the 60-day TTL limit. There is 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 is dense with information, covering purpose, arguments, response structure, and limitations. It is front-loaded with the core question. While not excessively long, it could be slightly more structured (e.g., bullet points), but it is efficient given the tool's 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?

Despite lacking an output schema, the description thoroughly explains the return values (tracked, expired, snapshot_dates arrays) and their contents, along with key limitations. This provides complete guidance for an agent to interpret the response and understand the tool's behavior.

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

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

Schema description coverage is 100%, so the schema already defines both parameters with defaults and constraints. The description reiterates this information without adding substantially new meaning beyond the schema, thus meeting the baseline for high coverage.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself implicitly from the sibling tool polymarket_edges, which likely provides current 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 implies usage for historical edge analysis but lacks explicit when-not or alternative recommendations. It provides context about when to use (to understand edge age) and limitations (60-day TTL, snapshot gaps), but does not directly contrast 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 no destructiveHint. The description adds significant behavioral detail beyond these: walking the ladder, returning specific fields like vwap_fill_price, slippage_pp, forced_directional_risk, and warnings about partial fills. 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 well-structured: one sentence for purpose, bold requirement, then clear mode breakdowns. Every sentence adds value, but some details could be condensed without losing clarity. Still very 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?

No output schema exists, so the description must explain return values. It lists all returned fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk for basket). With 4 parameters and no required fields in schema, the description clarifies constraints (one of market/event needed) and parameter limits (size_usd clamp). This fully compensates for the lack of output schema.

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

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

Schema coverage is 100% but parameter descriptions are minimal. The description adds rich semantics: side can be auto in basket mode, size_usd is interpreted differently for single vs basket, and clarifies mutual exclusivity of market/event despite both being optional in schema. Every parameter gains 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 is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and differentiates between single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage by explicitly being a pre-check before acting on arbitrage signals.

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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial basket fills convert arb into unhedged position). Also specifies that one of 'market' or 'event' is required, providing clear contextual rules.

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

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

The description adds significant behavioral context beyond annotations: it explains compatibility_warning scenarios (non-equivalent bet shapes, semantically unrelated events), temporal_alignment importance, and skipped_cross_type/subtype counters. Annotations already mark the tool as read-only and idempotent, and the description aligns with those.

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 information-dense, front-loading the main purpose and then detailing modes, response fields, and safety warnings. Every sentence adds value for a complex tool, though it could be slightly tighter.

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

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

With no output schema, the description fully explains return values (leg prices, matched spreads, compatibility_warning, temporal_alignment). It covers edge cases like mismatched bet shapes and unrelated events, making the tool completely understandable 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?

Schema coverage is 100% with descriptions for all three parameters. The description adds value by listing the 10 macro shortcuts and explaining the override logic for explicit parameters. This goes beyond what the schema alone provides.

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

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

The description clearly states it calculates cross-venue spread between Kalshi and Polymarket. It specifies two modes (topic macros and explicit parameters) and explains the response includes leg-by-leg prices and matched spreads. This distinguishes it from sibling tools like polymarket_arbitrage which focus on single-venue arbitrage.

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 guidance on when to use topic mode (10 pre-mapped shortcuts) vs explicit mode (custom pairings). It warns that most pre-mapped topics may return compatibility warnings, helping the agent avoid false expectations. However, it does not explicitly contrast with alternative 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no new behavioral traits beyond clarifying the input structure, so it provides little additional transparency.

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

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

The description is extremely concise with two sentences. It front-loads the main action and then briefly explains parameters. No superfluous 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?

Despite having no output schema, the description does not mention the response format (json-stat2). For a query tool, this is a significant omission as agents need to know what to expect. The description relies on the schema for this detail.

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

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

With 100% schema coverage, the description adds value by specifying that 'body is a PxWeb query object' and giving a concrete path example. This aids understanding beyond the schema's technical structure.

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

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

The description clearly states 'Pull data from a .px table', specifying the action and resource. It provides an example path but does not differentiate from sibling tools like 'table_meta', which might retrieve metadata.

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

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

The description implies usage for querying .px tables but gives no explicit guidance on when to use this tool versus alternatives such as 'table_meta' or 'search_within'. No when-not or prerequisite information is provided.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds value by explaining scoping (anonymous IP, key hash, account ID) and pairing with other tools. No contradictions.

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

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

Three sentences with no wasted words. Front-loaded with the core action, followed by use cases and scope.

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

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

For a simple tool with one optional parameter and solid annotations, the description fully covers behavior, usage, and limitations (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 coverage is 100%, so baseline is 3. Description adds meaningful context about the 'key' parameter (omit to list all keys) and clarifies what the key represents (memory key).

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

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

Description clearly states the tool retrieves a saved value or lists all keys, with specific verbs and resources. It distinguishes from sibling tools '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 (retrieve context) and implies when not (use forget for deletion). Provides context on scoping and pairing with remember/forget.

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

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

Annotations already indicate safe, read-only, idempotent operation. Description adds context on mark_read affecting next calls and that polls are fine. 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?

Concise paragraph with logical flow: purpose, return contents, filtering options, mark_read effect, and alternative access. Front-loaded with 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?

Describes return fields, parameters, and behavior. No output schema exists, but explanation of return content is adequate. Mentions alternative access method, providing 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%, but description adds behavioral context (e.g., mark_read flags read for future calls, since is ISO timestamp). Adds value 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?

Clearly states it pulls fired events from subscription feed and returns alerts with source, citation_uri, and payload. Does not explicitly differentiate from sibling tools but purpose is unambiguous.

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

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

Mentions that polling works fine and provides an alternative URL for scripts/dashboards. Gives guidance on filtering and mark_read behavior, but no explicit when-not-to-use or comparison with 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 indicate read-only, idempotent, non-destructive. Description adds valuable behavioral details: fans out to multiple APIs in one call, fallback mechanism, soft-fail for USPTO, and return structure (grouped changes with 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 paragraph of ~5 sentences, front-loaded with example queries. Every sentence adds unique value: purpose, sources, parameters, return format, alternative tool. No filler 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 multiple sources, fallback, and no output schema, the description is thorough: it explains what it returns (changes grouped by source, count, URIs), parameter semantics, and when to use alternative. Covers all necessary context for an 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%, and description adds meaning: clarifies 'type' only supports 'company', gives examples for 'since' (ISO date or relative shorthand like '7d'), explains 'value' can be ticker or CIK, and recommends typical monitoring values.

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 provides a change feed for a company in a time window, listing sources (SEC, GDELT/GNews, USPTO) and explicitly distinguishes from sibling tool entity_profile. Example queries are given, making the purpose immediately understandable.

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 example queries ("What's new with X", etc.), explains when to use vs entity_profile, and details fallback logic (GDELT preferred, GNews on rate limit). Also gives guidance on 'since' parameter ("Use '30d' or '1m' for typical monitoring").

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 include idempotentHint: true and destructiveHint: false. The description adds concrete behavioral details: key-value scoped by identifier, persistence differences for authenticated vs anonymous users (24h). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph with no wasted words. It front-loads the core purpose, includes usage context, and ends with pairing info. 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 simplicity of the tool (2 required parameters, no output schema), the description adequately covers purpose, scope, persistence, and pairing with siblings. It could mention the return type or success indicator, but the overall completeness is high.

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 key and value. The description provides example key patterns (e.g., 'subject_property') but does not significantly extend semantics beyond what the schema already offers.

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 examples like resolved ticker, target address, user preference, research subject. It distinguishes from sibling tools recall and forget by mentioning them as companions.

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

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

The description provides explicit guidance on when to use: 'when you discover something worth carrying forward.' It also mentions pairing with recall and forget, giving context. It does not explicitly state 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 mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds that it cascades through several lookup endpoints, replacing 2-3 manual lookups, and details return formats for each type (e.g., company returns ticker, CIK, company_name, citation URI). 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 concise yet comprehensive, with every sentence adding value. It starts with a clear purpose, then usage instruction, and then detailed supported types. 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?

For a lookup tool with 2 required parameters and no output schema, the description fully explains return values for each entity type, including citation URIs. Given the complexity and sibling tools, it covers all necessary context.

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

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

Schema coverage is 100% with enum for type and description for value. The description adds specific examples (e.g., 'ozempic', 'metformin') and explains auto-disambiguation for company inputs, providing 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 explicitly states that the tool resolves user-spoken names to canonical/official identifiers, with example queries like 'What's the ticker for...' and 'look up the ID for...'. It clearly distinguishes itself from siblings by being the first tool to use when needing an ID from a name.

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

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

The description says 'Use FIRST whenever you have a name but need an ID', indicating primary usage. It does not explicitly state when not to use it, but the context of sibling tools implies alternatives for downstream tasks. This is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: it probes each entity using ai_visibility_check, ranks by score, and returns 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 usage note, all front-loaded and concise. Every sentence adds value: what the tool does, how it works, and when to use it.

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 explicitly states return fields (score, confidence, signal density). It covers the use case, process, and parameter role, making it complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new parameter details beyond what the schema already provides (e.g., first entity as subject). The schema's parameter descriptions are already complete.

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, specifying the verb 'compare' and resource 'AI presence'. It distinguishes itself from sibling tool 'ai_visibility_check' by being a multi-entity comparative version.

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 a clear use case ('competitive AI-marketing audits') and an example question, implying when to use the tool. However, it does not explicitly state when not to use it or mention alternatives beyond the obvious sibling distinction.

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

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

Describes behavioral traits beyond annotations: composite call, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed lists if timeout. 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?

Single paragraph packed with necessary information, front-loaded with purpose. 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?

Comprehensive: explains return values (summary block, per-advisory detail, links, alternative versions) and warns about partial failures. 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 coverage is 100%, and the description confirms that scoped packages are accepted and version defaults to latest, adding small but useful 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's a composite check for 'should I add this npm package to my project' in one call, specifying it fans out across deps.dev and bundlephobia. It distinguishes from sibling tools by stating NPM ecosystem only in v1.

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: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also mentions NPM ecosystem only and provides alternatives for other ecosystems.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings, cosine over 500-char overlapping windows, 200K char cap with truncation flag.

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?

Concise and well-structured: front-loaded with core purpose, then use case, then pairing, then technical 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?

No output schema, but description fully explains return format (passages with offsets and scores). Covers use case, capabilities, limits, and pairing, making it complete for a tool with 3 parameters and simple functionality.

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 repeats similar information to schema (text is fetched record, query is natural language) but adds no new parameter-specific details 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?

Clearly states 'semantic search INSIDE a fetched record', specifying verb (search), resource (text inside a record), and distinguishing from siblings by mentioning pairing with ask_pipeworx_grounded and use case of large records.

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 when the record is too big to cram into the prompt' and explains benefits, but does not explicitly state when not to use it (e.g., when text is short).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context beyond annotations by explaining the two entry types and how to interact with them, which is valuable but not extensive.

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

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

The description is two sentences, front-loaded with the main purpose, and each sentence adds essential information without redundancy. It is highly concise 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?

Given no output schema, the description explains the entry types and their ids, allowing an agent to infer the response structure. It does not explicitly describe the response format (e.g., list of entries), but the context is sufficient for a navigation tool. Slight gap for completeness.

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

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

The schema already provides 100% coverage for the single parameter 'path' with a clear description and examples. The tool description reiterates the default and examples, adding marginal value. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Navigate' and the resource 'subject tree', and distinguishes the two entry types (folders vs tables) with specific actions (drill in vs use with table_meta/query_table). This differentiates it from sibling tools like table_meta and query_table.

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

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

The description provides explicit guidance: for folder entries (type 'l') drill in with id; for table entries (type 't') use with table_meta/query_table. It also notes the default root path. Although it doesn't explicitly state when not to use, 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 provides significant behavioral context beyond annotations: creation returns a subscription ID, delivery channels with constraints (SMS cap, phone verification, webhook signing secret returned once, auto-disable after 10 failures). It aligns with annotations (readOnlyHint=false, idempotentHint=true) and adds valuable operational details.

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 the main purpose first, followed by requirements, type examples, and delivery details. It is dense but not wasteful; each sentence adds necessary information. Slightly longer than ideal, but justified by complexity.

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

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

Given the tool's complexity (multiple types, delivery channels, prerequisites), the description covers the essential aspects: authentication, type-specific parameterization, and delivery channel behavior. It does not describe the return value format (no output schema), but the description mentions returning a subscription id. Overall complete for the agent's needs.

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 coverage is 100%, but the description adds concrete examples for each type and delivery option, including constraints not in the schema (SMS cap, phone verification, webhook secret one-time return). This adds meaningful value beyond the 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 uses a specific verb ('Create a proactive monitoring subscription') and resource ('live-data event stream'), clearly distinguishing it from sibling tools like list_subscriptions and unsubscribe. It avoids tautology and provides a concrete purpose.

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

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

The description explicitly states the prerequisite (Pipeworx OAuth account) and lists supported types with example parameters. While it doesn't directly compare to sibling tools, the context of creating vs. listing/subscribing is implicit. Could be improved by a brief note on when to use this vs. other subscription management 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds behavioral context: it returns 'category-bucketed example questions' drawn from a 'live catalog of thousands of tools,' and explains the output shape. It could mention error handling for invalid topics, but overall adds value beyond annotations.

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

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

The description is multi-sentence but each sentence serves a purpose: stating the purpose, listing categories, detailing output, and providing usage guidance. It's front-loaded with key trigger phrases ('What can I ask Pipeworx?'). Minor redundancy could be removed, but overall it's efficient for the information conveyed.

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 one optional parameter and no output schema, the description thoroughly covers the tool's purpose, input, output format, and usage context. It explains the output structure (category-bucketed example questions with tool+argument shape) and notes it's drawn from a live catalog. No gaps remain for an agent to infer.

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

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

Schema coverage is 100% with a description for the 'topic' parameter. The description enriches this by specifying possible values (e.g., 'finance', 'pharma') and usage advice: 'Call with no arguments for the full spread, or pass topic to focus.' This adds practical guidance beyond the schema's enum-like list.

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: returning category-bucketed example questions with tool+argument shapes. The title 'What Can I Ask Pipeworx?' is descriptive, and the description explicitly labels it as 'the onboarding entry point,' distinguishing it from siblings like 'discover_tools' or 'ask_pipeworx'.

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

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

The description provides explicit guidance: '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 explains when to call with no arguments vs. with a topic, and mentions using it for onboarding. While it doesn't explicitly state when not to use it, the context implies it's for initial exploration, which 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 readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds the constraint that the path must point at a '.px' table, which is useful behavioral context. However, it does not disclose behavior for invalid paths or other edge cases.

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

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

The description is extremely concise—one sentence followed by an example—with no wasted words. It is front-loaded and directly communicates the tool's purpose and a key usage constraint.

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 parameter set and annotations, the description is adequate. It explains what the tool returns (table definition) and the required format. However, it is vague about what exactly the 'table definition' includes, and lacks details about the return structure.

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 for the single parameter 'path' is 100%, with the schema description already providing an example and format. The tool description adds the explicit '.px' requirement, which is marginally helpful but does not significantly augment 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 'table definition (dimensions, valid values)', which indicates it retrieves metadata about a table. The verb is implied and the resource is unambiguous, distinguishing it from siblings like 'query_table' and 'search_within'.

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 an example path format but does not explicitly state when to use this tool versus alternatives. The context of siblings implies differentiation, but no exclusions or usage rules are provided.

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

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

The description adds significant behavioral context beyond annotations: it clarifies that the row is deactivated not deleted, so historical events remain available via recent_alerts. Annotations only indicate non-read-only and non-destructive, but the description enriches the understanding of the operation's effects.

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

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

Two sentences, no wasted words, front-loaded with the main action. Every sentence provides essential 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's simplicity (1 parameter, no output schema), the description fully covers its behavior: what it does (cancel), constraints (ownership), and consequences (deactivation, historical data retention). 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 already describes the id parameter as 'Subscription id (uuid) returned by subscribe.' The description does not add additional semantic details about the parameter beyond what the schema provides, so it meets the baseline but does not add extra value.

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 cancels a subscription by id, using specific verb 'Cancel' and resource 'subscription'. It distinguishes from deletion by noting deactivation rather than deletion, differentiating from a potential delete 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?

The description explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), which guides who can use it. However, it does not explicitly state when to use this tool over alternatives like subscribing again or listing subscriptions, though the mention of 'recent_alerts' provides some context for post-cancellation behavior.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context: the tool returns a verdict with extracted values and citations, and replaces multiple sequential calls. It also clarifies the data source (SEC EDGAR + XBRL) and scope (company-financial). 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 well-structured: starting with example triggers, then usage, then scope, then output details. It is informative without being verbose, though a slight trim could improve conciseness.

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

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

Given a single parameter with full schema and no output schema, the description provides comprehensive information: the return verdict types, citation format, and the tool's efficiency advantage. It covers everything an agent needs to use this tool correctly.

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

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

Schema coverage is 100% with a clear description for 'claim' (natural-language factual claim with examples). The description reinforces this but does not add new technical details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It lists example invocations ('Is it true that...', 'fact check') and specifies the domain (US public companies via SEC EDGAR + XBRL), distinguishing it from sibling tools that likely don't handle structured claim verification.

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

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

The description explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It provides natural-language trigger phrases. However, it does not mention when not to use or list alternative tools for non-financial claims, which would strengthen guidance.

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