Nsf Awards

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: pricing (free for default, BYO key for Anthropic), key passthrough behavior, and that the tool returns a combined view plus per-model details. It does not contradict annotations. Minor omission: no mention of rate limits or potential costs for the free tier.

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

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

The description is four sentences, front-loaded with the core purpose, followed by key details (default model, optional key), and ending with use cases. Every sentence adds value; no redundancy or fluff.

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

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

Despite lacking an output schema, the description explains the return structure: per-model fields (score, confidence, signals, raw_response) and a combined view. Combined with 100% parameter coverage and clear annotations, this provides sufficient completeness for an agent to understand input/output 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 coverage is 100%, and the description adds significant meaning beyond the schema. It explains the 'entity' parameter with examples, clarifies that 'models' defaults to 'workers-ai', details that '_apiKey' is passed directly to Anthropic, and gives context about 'context' for disambiguation. This enriches the agent's understanding of 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 specifies a clear verb ('probe'), resource ('one or more LLMs'), and outcome ('score visibility 0-100 per model'). It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on a single entity's visibility across models, making its purpose unique and unambiguous.

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

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

The description provides clear usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains default vs. Anthropic model selection and key handling. However, it does not explicitly state when not to use this tool or list alternatives (e.g., 'scan_competitor_ai_presence' for multi-entity comparisons), which would strengthen the 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 indicate safe, read-only, idempotent behavior (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). The description adds value by explaining the routing mechanism (chooses from 5,564 tools), argument filling, and return format (structured answer with citation URIs). It also mentions speed and tier compatibility. The one missing piece is explicit confirmation that no mutations occur, but annotations cover that. No contradiction.

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

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

The description is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and structured with clear sections: use cases, examples, step-up alternatives. Though lengthy, every sentence adds value. Minor deduction for slight redundancy in listing domains both early and in examples.

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

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

Given the tool's complexity (6 params, 1 required, no output schema), the description is quite complete. It explains what the tool does, when to use it, how it internally routes, and what the return format is (structured with citations). Examples in the schema compensate for lack of output schema. Could mention language support or guarantee of citation format explicitly.

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 multiple aliases documented and examples provided. The description itself does not add extra meaning beyond what the schema already conveys about the natural language question. Baseline is 3 given high coverage; the description is sufficient but not superlative.

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: it is a primary entry point for factual questions about real-world entities, events, or numbers, and explicitly lists supported domains (SEC filings, FDA, economic stats, etc.). It distinguishes itself from siblings by naming alternatives like ask_pipeworx_grounded and deep_research for specific use cases.

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

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

The description provides explicit when-to-use guidance: 'Use whenever the user asks ...' with specific query phrases, and includes examples. It also tells when NOT to use it ('Step up only when needed') and directs to alternatives for broader or more evidence-heavy queries. This is comprehensive and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds meaningful context beyond these: it explains the experimental nature of the beta, the current inactive state of candidates (last retired on 2026-07-26), the comparison process against the stable router, and the fact that the tool is fully functional. 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 front-loaded with key identity and differentiation information. Each sentence serves a purpose: defining the beta, stating identity, describing experimental state, giving usage guidance, and clarifying behavior. It is slightly longer than strictly necessary but well-structured and efficient.

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

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

Despite lacking an output schema, the description fully covers what an agent needs: the tool's identity, current state (no active candidate), relationship to the stable router, usage context, and fallback behavior. It acknowledges the complexity (5,564 tools) and provides sufficient context for correct invocation.

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

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

Schema coverage is 100% with 6 parameters all documented as aliases for 'question'. The description merely references 'same arguments' without adding semantics beyond the schema. Baseline score of 3 applies since schema does the heavy lifting and description adds no new parameter information.

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

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

The description clearly states that the tool is a beta version of ask_pipeworx, functioning as an identical universal router with candidate routing improvements. It explicitly distinguishes itself from the sibling ask_pipeworx by noting the experimental edge and live candidate testing, while also specifying the tool's scope (5,564 tools, same arguments, same response shape).

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 it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also clarifies that the tool is a full working router with no fallback behavior, setting clear expectations for when to choose this over the stable version.

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

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

Description provides rich behavioral context beyond annotations: hallucination-resistant extraction, explicit refusal reasons (not_in_source, no_tool_match, etc.), routing over 5,564 tools, extra LLM cost. Annotations only indicate idempotent, read-only, open-world — description fills in critical operational details without contradiction.

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

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

Extremely concise: five sentences covering purpose, mechanism, output format with refusal reasons, usage guidance, and trade-off cost. Every sentence carries essential information, no redundancy. Front-loaded with the core concept of hallucination resistance.

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

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

Given the tool's complexity (routing over thousands of tools, extracting answers) and that there is no output schema, the description comprehensively covers: what it does, how it works, return structure on success and failure (with specific refusal reasons), and exact usage context. No gaps remain for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100% (all 6 parameters documented with descriptions), so baseline is 3. The description does not add parameter-level semantics beyond what the schema provides (e.g., format, length, examples). The description mentions 'question in natural language' which is already in the schema.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads that extracts answers only from tool results. It uses specific verbs (extracts, returns) and explicitly distinguishes itself from sibling ask_pipeworx by emphasizing groundedness and refusal behavior.

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

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

Explicit usage guidance: use when answers will be quoted/cited/acted on (financial, legal, medical); prefer ask_pipeworx for casual lookups due to extra LLM cost. This provides clear when-to-use and when-not-to-use with concrete examples and compares to an alternative 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?

The description extensively discloses behavioral traits beyond annotations, including classifier system, fan-out examples, response shapes, resolver contract (confidence levels, alternatives), parent_event extractor, news fallback fields, safety short-circuits for low confidence or closed markets, wide-spread illiquidity notes, and resolution-rule risk. 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 very long and verbose, with multiple paragraphs of detailed examples and edge cases. While well-structured with clear sections, it lacks conciseness. Not every sentence earns its place; some fan-out examples could be truncated or referenced in documentation.

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 covers all aspects: input resolution, classifier fan-out, response structure (market, analysis, evidence), resolver contract, parent_event, news fields, safety mechanisms, and resolution rules. It is exceptionally complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples and context (e.g., market input formats, depth behavior) but does not significantly supplement the existing parameter descriptions. The added value is moderate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research) and resource (Polymarket bet), and provides specific use cases like 'should I bet on X.' It distinguishes from siblings by detailing comprehensive fan-out behavior, implying it's for in-depth research rather than simple queries.

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

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

The description explicitly says 'Use for should I bet on X...' providing clear when-to-use guidance. However, it does not explicitly mention when not to use this tool or name alternative tools for simpler tasks. The implicit context is sufficient but not fully explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, etc. The description adds beyond that: details on data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. No contradictions with annotations.

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

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

Well-structured with front-loaded example queries. Approximately 120 words, every sentence adds value. Slightly verbose in listing examples but still efficient for the richness of information.

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

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

For a tool with no output schema, the description adequately covers what the agent can expect: paired data, citation URIs, sorted results, and the specific metrics retrieved for each entity type. Also mentions limits (2-5 entities) and efficiency gains (replaces 8-15 sequential lookups). Complete enough to guide correct invocation.

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

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

While schema coverage is 100% and both parameters are described, the description adds significant meaning: for 'type' it specifies exactly what data is pulled (revenue, net income, cash, debt for companies; adverse-event counts, FDA approval counts, trial counts for drugs). For 'values' it gives examples (tickers/CIKs for companies, drug names). This goes well beyond the schema's enum and array description.

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

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

The description clearly states it performs side-by-side comparisons of 2-5 companies or drugs, with example queries. It distinguishes from sibling tools like entity_profile (single entity lookup) by specifying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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

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

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also gives concrete examples (e.g., 'which is bigger', 'rank these companies') that help an agent decide when to use this tool.

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

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

Annotations already mark the tool as read-only, idempotent, non-destructive, and open-world. The description adds rich detail: returns fine-grained findings with citations, has gap recovery, contradiction scans for certain depths, semantic excerpting of large records, and expected latency ranges (15-60s, up to 90s). 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 packed with valuable information but is very long (multiple paragraphs). It front-loads critical prerequisites (account + restriction) but later sections on second-hop iteration and large record excerpting could be more concise. Every sentence earns its place, but overall density hurts readability.

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

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

For a tool with 2 params and no output schema, the description covers prerequisites, scope, limitations, depth behaviors, return value structure (findings packet with evidence, confidence, source, citations, gaps, contradictions), and performance expectations. It is nearly complete; minor gap: doesn't explicitly state that output may be a list/findings packet structure, but the description strongly implies it.

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

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

Schema description coverage is 100% and both params (depth, question) are already well-described in the schema. The description adds clarity on the 'depth' enum by explaining the parallel facets count, hop behavior, and contradictions scan per tier, but the schema already covers the core semantics. A 4 is appropriate for adding moderate value beyond the schema.

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

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

The description explicitly states the tool performs 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and decomposes questions into facets, routing to 5,564 tools in parallel. This clearly distinguishes it from siblings like ask_pipeworx (single lookup) and bet_research (likely different domain).

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

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

Provides explicit when-to-use guidance ('best for broad/multi-part questions over structured data'), when-not-to-use ('For BREAKING or colloquial CURRENT-NEWS...prefer ask_pipeworx'), and an alternative tool for unsigned-in users (ask_pipeworx). Also mentions account requirements and paid plan restriction for 'thorough' depth.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context about the return format (top-N tools with full schemas, ready to call) and 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?

Two sentences: first states purpose and domain list, second details return value and usage instruction. Front-loaded and every sentence is essential, 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?

With 6 parameters (many aliases) and no output schema, the description provides sufficient context for the discovery tool: returns top-N results with full schemas. Missing explicit mention of default limit or max, but that is in 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% with detailed descriptions. The description adds domain-specific context (examples of queries like 'analyze housing market trends') and explains that aliases (q, task, search, description) are accepted, going beyond the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and provides numerous specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools by emphasizing it is the first call to browse the option set.

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 'Call this FIRST when you have many tools' and provides scenarios like 'want to see the option set'. While it doesn't explicitly state when not to use, the context makes it clear that this is for discovery, not for direct answers.

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

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

Annotations already confirm readOnly, openWorld, idempotent, non-destructive. Description adds value by detailing data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific return fields, and soft-fail behavior for patents. No contradictions with annotations.

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

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

Description is front-loaded with purpose and usage examples. It is comprehensive but not overly verbose. A bit lengthy due to example utterances, but each sentence adds value.

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

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

Given the tool's complexity (multiple data sources, soft-fails, no output schema), the description fully covers inputs, behavior, and return structure. It leaves no ambiguity about what the tool does or how to use it.

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

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

Schema coverage is 100%, but description adds meaning by specifying that 'type' only supports 'company' and providing examples for 'value' (ticker or CIK). It clarifies what is not supported (names), adding context beyond the schema comments.

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?

Uses specific verbs like 'full cross-source profile' and lists example queries ('Tell me about X', 'research Acme', etc.). Clearly distinguishes from sibling tools by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'.

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

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

Explicitly states when to use ('when the user asks for a holistic view') and when not to use ('Names not supported — use resolve_entity first if you only have a name'). Provides direct alternative for name inputs.

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's 'delete' aligns but adds minimal new behavioral context (e.g., 'clear sensitive data'). No contradiction.

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

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

Three sentences with clear purpose, usage context, and sibling references. Front-loaded and 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 one parameter, no output schema, and clear annotations, the description fully covers the tool's role and usage 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 description coverage is 100%. The description only mentions 'by key' which matches the schema's parameter description. No additional semantics beyond schema.

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

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

The description clearly states the action ('delete'), the resource ('previously stored memory'), and the method ('by key'). It distinguishes itself from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use the tool: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with complementary tools.

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

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

Annotations already declare the tool as read-only, idempotent, safe, and non-destructive. The description adds valuable behavioral context by detailing the process: fetches the page, extracts title/description/key links, and emits standard markdown format. 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: first defines core functionality, second explains process, third lists use cases. No wasted words, front-loaded with key 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 simple tool (2 parameters, no output schema), the description fully explains what the tool does, how it works, and what the output is. It is complete and self-contained.

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

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

Schema coverage is 100% with clear parameter descriptions. The description does not add new information about parameters beyond what the schema provides, so it meets but does not exceed 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 clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and purpose. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on creating the file rather than checking 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 lists concrete use cases (getting a client's site indexed, drafting for own project, auditing competitors) and implies when to use. It does not explicitly state when not to use or provide alternatives, but the context is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds value by detailing the returned content (abstract, outcomes report, PI info), going 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?

Single sentence with no wasted words, clearly and efficiently conveys the tool's function.

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

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

Given the presence of an output schema and clear single-parameter input, the description sufficiently covers what the tool does and returns.

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

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

Schema coverage is 100% with clear description for award_id. Description adds 'by ID' but no additional meaning beyond 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?

Description clearly states it fetches a single NSF award by ID, with specific resources (abstract, outcomes, PI info), distinguishing it from sibling search_awards which likely handles multiple awards.

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 use for fetching a single award, but does not explicitly state when not to use it or suggest alternatives like search_awards for multiple awards.

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 value by listing the return fields and noting the parameter behavior (active vs inactive), but does not provide additional behavioral context beyond that.

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 concise sentences, each earning its place. No redundant or extraneous information.

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

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

For a simple read-only list tool with one optional parameter, the description is fully adequate. It explains the return fields and offers usage guidance, making it complete for an agent.

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

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

Schema description coverage is 100%, and the single parameter 'include_inactive' is already well-described in the schema. The description does not add new information about the parameter's meaning or format.

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 lists the caller's active subscriptions and specifies the returned fields. It distinguishes the tool from siblings 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 context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implicitly guides the agent away from alternatives, though it does not name them directly.

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 provide no safety hints (all false), so the description carries full burden. It discloses the rate limit ('5 per identifier per day'), the fact that filing without an account returns a claim_token, and that the team reads digests daily and signal affects roadmap. These are non-obvious behavioral traits essential for an agent.

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

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

The description is dense but not bloated; every sentence provides actionable information. It is front-loaded with the core purpose first, but the long paragraph could benefit from bullets or paragraph breaks for readability. Still, it earns its length.

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

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

The tool has no output schema and no required parameters, yet the description explains the return behavior (claim_token), the input expectations (structured context, plain message, max 2000 chars implied by schema), and operational constraints (rate limit, free). This is a complete picture for an agent to decide and invoke correctly.

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

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

The schema already covers all four parameters with descriptions, meeting the 100% coverage baseline. The description adds value by clarifying the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and specifying message content rules ('don't paste the end-user's prompt'), which are not in the schema.

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

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

The description opens with a clear directive ('Tell the Pipeworx team something is broken, missing, or needs to exist') and immediately enumerates the four categories (bug, feature/data_gap, praise). It distinguishes this tool from sibling informational tools like ask_pipeworx by focusing on feedback submission.

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

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

Explicitly lists conditions for use (bug, feature/data_gap, praise) and provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also explains the claim_token follow-up mechanism, giving the agent concrete steps for when to use this tool versus 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: self-aggregating signal, no PII, derived from CF analytics-engine, caching behavior (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, front-loaded with the primary purpose, each sentence adding distinct value. No fluff or redundancy.

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

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

The tool has no output schema, but the description explains return fields (top tools, packs, call volume) and caching. For a simple read-only tool with one param, all necessary context is provided.

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% (1 param with enum). The description adds meaning beyond the schema by explaining that shorter windows surface 'hot right now' while longer windows show 'steady-state demand', and notes default is 24h.

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 ('Returns') and clearly identifies the resource (top tools, top packs, total call volume over a recent window). It distinguishes itself from siblings like 'discover_tools' or 'ask_pipeworx' by focusing on trending/usage statistics.

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 three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). While it doesn't state when not to use it or name alternatives, the guidance is clear and actionable.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: explain semantic anchors, partition filters, fill checks, and response structure. No contradiction exists, and the description significantly enhances 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 thorough but lengthy and presented as a single dense paragraph. While every sentence adds value, better structuring (e.g., sections for each mode) would improve agent readability. It is not overly concise but avoids redundancy.

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

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

Given the complexity (three modes, no output schema), the description is highly complete. It covers edge cases (placeholders, similarity threshold, fill checks), describes the response structure, and references sibling tools for further actions. No gaps remain.

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

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

Both parameters have descriptions in the schema (100% coverage). The description adds further meaning: for 'event', it explains what event slugs are and that full URLs are accepted; for 'topic', it clarifies the cross-event scanning behavior and seed question format. This goes beyond the schema.

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

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

The description clearly identifies the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools by specifying its unique function.

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

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

The description explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also provides examples and directs to an alternative tool (polymarket_fill_risk) for custom sizing, covering both when to use and when not to.

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 read-only, open-world, idempotent, non-destructive. The description adds caching details, model families, edge calculation, and why Fed bets are excluded. 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 verbose with detailed model family explanations that may be excessive for tool selection. While front-loaded with purpose, it could be more concise.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, diagnostics, fed_candidates) and caching. It covers all necessary context for an agent to use the tool effectively.

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

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

With 100% schema coverage, baseline is 3. The description adds meaningful usage guidance for parameters like slippage_pp, min_liquidity, and min_kelly, including real-world context and tradeable-edge filter labels.

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 to find opportunities where Pipeworx data disagrees with market price. It is built for daily discovery and distinguishes from sibling tools like polymarket_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 implies usage for discovering betting opportunities without paging. It explains parameters for filtering but does not explicitly compare with sibling tools or state when not to use this tool.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: uses daily snapshots, response structure (tracked, expired, snapshot_dates), limits (60-day TTL, no intraday). 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 with clear sections (purpose, args, response, limits). It is not overly verbose; each sentence adds value. Could be slightly more concise, but overall effective.

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

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

Given no output schema, the description thoroughly explains the return values (tracked, expired, snapshot_dates). It also covers limitations (TTL, start time, no intraday). The description is complete and anticipates user questions.

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 adds meaning by clarifying defaults and clamps for 'days', and options for 'window', plus how parameters affect the response (lookback, snapshot family). This adds value beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on time-series analysis rather than current snapshots.

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

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

The description implicitly tells when to use (to assess edge persistence and decay), but does not explicitly contrast with alternatives or provide when-not-to-use guidance. The context about fresh vs. old edges helps orient the user.

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

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

The description discloses behavioral traits beyond annotations: it walks the ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about partial fills and forced directional risk. Annotations already indicate read-only, idempotent, open-world, and non-destructive, and the description adds rich behavioral context without contradiction.

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

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

The description is long but well-structured: starts with purpose, then details modes and parameters, then outcomes. Every sentence earns its place, though it could be slightly more concise. The front-loading of key information is good.

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

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

The description is complete: it covers both modes, parameter defaults, return values (even without output schema), use cases, and warnings. No gaps for the agent to guess.

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 adds significant meaning: explains side options and defaults, clarifies size_usd as settlement notional for baskets, and describes the return fields in detail for both modes. This goes well beyond the schema.

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

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

The description clearly states it checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes between single-market and basket modes with detailed mode-specific behaviors. It explicitly differentiates from sibling tools by specifying when to use this tool (before acting on arb signals or large trades).

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (partial fills convert arb into unhedged directional position). It provides clear context for when to use and when not use, including thresholds.

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?

Despite annotations providing readOnlyHint and idempotentHint, the description adds extensive behavioral context: compatibility_warning conditions, temporal_alignment, skipped cross types, and the equivalence of bet shapes. It discloses that real cross-venue spreads are rare. No contradiction with annotations.

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

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

The description is detailed and well-structured with clear sections (two modes, response fields, safety fields). It front-loads the purpose and uses bullet-like formatting. While verbose, every sentence adds value. Minor improvement could be trimming redundancy about pre-mapped topics.

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

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

Given the tool has 3 parameters, no output schema, and no nested objects, the description provides complete context: explains response fields (leg-by-leg prices, top spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and when spreads are meaningful. The agent can correctly interpret results.

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

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

Schema coverage is 100%, and the description adds significant value beyond the schema: lists the 10 pre-mapped topics with examples, explains override behavior for explicit tickers, and provides usage examples. This fully compensates for any schema limitations.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and provides two distinct modes (topic shortcuts and explicit tickers).

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 explains when the spread is meaningful (equivalent bet shapes) and when it's not (compatibility_warning scenarios, temporal misalignment). It also warns that most pre-mapped topics may not be tradeable. However, it could be more explicit about when to use this tool versus alternatives 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 indicate readOnly and non-destructive behavior. The description adds scoping to user identifier and the ability to list all keys when omitted. No contradiction. Could mention idempotency explicitly but not required.

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. First sentence states core function, second provides usage context and examples, third covers scoping and tool relationships. Front-loaded and 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?

For a simple tool with one optional parameter, the description fully covers purpose, usage, scoping, and relationships. No missing information given the tool's simplicity and existing annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that omitting the key lists all keys and giving examples. This aids understanding beyond the schema.

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

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

The description uses specific verbs ('Retrieve', 'list') and clearly identifies the resource (values saved via remember). It distinguishes itself from siblings by mentioning remember and forget, and provides concrete examples like ticker, address, research notes.

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: to look up context stored earlier without re-deriving from scratch. Also mentions scoping and pairing with remember/forget, giving clear guidance on alternatives.

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

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

The description adds value beyond annotations by explaining the return fields (source, citation_uri, payload), the effect of mark_read on subsequent calls, and that polling works well. It does not contradict any 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 and relatively concise, starting with the main purpose, then details on return fields, filtering, and a note on alternative access. However, it could be slightly shortened without losing clarity.

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

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

The description covers the essential aspects given the tool's complexity: return fields, filtering, mark_read, and alternative access. However, it does not mention ordering (most recent is implied but not explicit) or any pagination details beyond limit. For a read-only tool, this is adequate but not fully 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?

The schema already has 100% coverage with descriptions, but the description adds practical context such as an example type ('sec_8k'), clarifies ISO timestamps, and explains the mark_read flag behavior, which enhances the parameter semantics beyond the schema.

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

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

The description clearly states the action ('Pull') and resource ('fired events from your subscription feed'). It distinguishes itself from sibling tools by focusing on events rather than subscriptions or other entities.

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

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

The description provides some usage context, such as how to filter and use mark_read, but it does not explicitly mention when to use this tool over sibling tools like list_subscriptions or when not to use it. The mention of an alternative REST endpoint is helpful but not a sibling comparison.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description discloses fans-out to multiple sources, fallback logic, soft-fail for USPTO, and return structure (changes grouped by source, total_changes, citations). No contradiction with annotations.

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

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

Description is moderately long but front-loaded with query examples. Each sentence adds value (usage, sources, parameter guidance, alternative tool). Slightly verbose but well-structured.

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

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

Despite no output schema, description completely explains return format (changes grouped by source, total_changes, citations) and covers edge cases (USPTO soft-fail). For a multi-source tool with 3 required params, this is exhaustive.

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 significant value: explains 'since' formats (ISO date, relative shorthand) with examples, recommends '30d' or '1m' for monitoring, clarifies 'value' accepts ticker or CIK. No ambiguity.

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 'change feed for a company' and distinguishes from sibling 'entity_profile' by contrasting static profile vs. change feed. It also maps to user queries like 'what's new with X', making purpose explicit.

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

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

Provides explicit when-to-use examples (e.g., 'latest on Y', 'updates on Acme') and when-not-to-use ('Use entity_profile instead for static profile'). Also details fallback behavior (GDELT→GNews) and window parameter interpretation.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds behavioral traits: key-value store scoped by agent identifier; persistent for authenticated users; 24-hour retention for anonymous sessions. 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?

Two short paragraphs, each sentence adds value. Front-loaded with purpose. Could combine some redundancy (e.g., 'scoped by your identifier' and later 'Authenticated users...') 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, but description covers storage details (persistence, scoping, pairing). Sufficient for correct invocation. Lacks mention of maximum size or key naming rules, but those are implied by schema examples.

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 schema descriptions already include examples. The description rephrases key and value but does not add new meaning beyond what the schema provides. This matches the baseline score for full schema 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 uses specific verbs ('Save data...reuse later') and noun phrases ('cross session memory'). It lists concrete examples such as ticker, address, user preference, which make the resource clear. It also explicitly distinguishes from sibling tools recall 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 states when to use: 'when you discover something worth carrying forward'. It provides examples such as resolved ticker, target address. It also tells the agent to pair with recall for retrieval and forget for deletion, giving clear context vs. alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it cascades through several lookup endpoints internally, degrades gracefully (if GLEIF or OpenFIGI is unavailable, EDGAR identifiers still return), and explicitly states that unresolved identifiers are stated under 'unresolved' rather than omitted. 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 front-loaded with example queries and clear purpose, but it is quite verbose (multiple paragraphs). While all information is valuable, some sentences could be streamlined without losing meaning. The structure is logical, but conciseness is slightly reduced by the detailed explanations.

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 (resolving entities across multiple sources with graceful degradation, unresolved identifiers, and multiple input formats), the description is comprehensive. It covers all necessary aspects: supported types, input formats, output details, fallback behavior, and source attribution. Even without an output schema, the description provides enough information for the agent to understand what will be returned.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds substantial meaning beyond the schema: for 'type', it explains each type's capabilities (e.g., company cross-source identity spine, drug RxNorm citation). For 'value', it gives examples (ticker, CIK, ISIN, name) and explains behavior for ISIN input (maps to legal entity via GLEIF). This enriches the agent's understanding of valid inputs and expected behavior.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers. It gives specific example queries ('What's the ticker for…', 'find the CIK for…') and lists supported entity types (company, drug) with detailed explanations of what each type returns. This differentiates it from sibling tools like compare_entities or 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It provides clear context for when to use the tool (when you have a name but need identifiers) and implies when not to use it (if you already have IDs). It also mentions that using resolve_entity replaces 2-3 manual lookups, guiding the agent on efficiency.

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 readOnly, openWorld, idempotent. Description adds that it probes each entity with ai_visibility_check, ranks, and returns score/confidence/signal density. No contradiction.

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

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

Two sentences, first states purpose, second provides context and output. Front-loaded and 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?

Given complexity (multi-entity, sub-calls, no output schema), description fully explains operation, inputs, output structure, and use case. 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 covers all 4 parameters with descriptions. Description adds context about first entity being subject, which is not in schema. No further parameter detail needed.

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 compares AI visibility across multiple entities side-by-side using ai_visibility_check. It specifies ranking and output (most/least recognized), and distinguishes from siblings like ai_visibility_check.

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

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

Explicitly says 'Useful for competitive AI-marketing audits' and gives an example question. Implies when to use (multi-entity comparison) vs single entity check (ai_visibility_check). Also states first entity is subject.

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

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses important behaviors: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s and will be listed in sources_failed if it times out, and the return structure includes summary block, per-advisory details, links, and alternative versions.

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: a clear first sentence for purpose, followed by specifics. It is moderately long but every sentence adds value. Could be slightly more concise, but still effective for an agent.

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

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

Given the tool's complexity (multiple data sources, partial failures) and the absence of an output schema, the description is remarkably complete. It covers the return fields, behavior on timeout, and ecosystem limitations, ensuring the agent can use it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds minimal extra meaning—it mentions scoped packages are accepted and that version defaults to latest, which is already in the schema. No additional semantics beyond the schema.

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

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

The description clearly states the tool's purpose as a composite check for adding an npm package, specifying the data sources (deps.dev, bundlephobia) and the aspects evaluated (license, advisories, version history, bundle size, etc.). It distinguishes itself from siblings by noting the NPM-only scope 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 says when to use this tool: whenever an agent asks about safety, popularity, size, or cost of adding a package. Also clarifies ecosystem limitations (NPM only) and directs other ecosystems to a different tool (deps.dev:version).

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. Description adds the return fields (title, PI, etc.), complements annotations without contradiction.

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

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

Two sentences: first summarizes purpose and filters, second describes output and alternative. No waste, information is front-loaded.

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

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

Given output schema exists, description explains return fields. Covers purpose, filters, returned data, and alternative. Complete for a search tool with rich annotations.

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

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

Schema coverage is 100% so baseline is 3. Description lists filters but does not add meaning beyond what schema already provides for each parameter.

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

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

Description clearly states 'Search NSF awards' and lists all filter criteria. It distinguishes from sibling tool 'get_award' by noting that tool is for full abstract and outcomes report.

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 this tool (searching) and when to use alternative (get_award for detailed data). Provides clear context for tool selection.

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

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

Adds value beyond annotations: details embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K chars with truncation flag), and that passages have offsets for verification. No contradiction with idempotent/readOnly hints.

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: front-loaded with main purpose, then technical details. Each sentence adds value, though could be slightly shorter.

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 3 params and no output schema, description explains return format (passages with offsets and scores), technical constraints, and use case completely.

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 example queries for 'query' parameter and default value for 'limit', enhancing understanding beyond schema.

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

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

Clearly states 'semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article) and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt' and provides alternatives: 'fetch with the gateway, ground over the relevant passages instead of the whole document.'

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, such as the requirement for a Pipeworx OAuth account, the return of a subscription id, delivery channel specifics (email/SMS caps, webhook auto-disable after 10 failures). No contradiction with annotations.

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

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

The description is dense but not overly long. It front-loads the purpose and covers all aspects. Minor improvement could be structuring with bullet points for readability, but current format is acceptable.

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 value ('Returns the new subscription id'), covers all parameters, prerequisites, and limitations. It is fully complete for a subscription creation tool.

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

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

With 100% schema coverage, the description still adds substantial value by providing detailed examples for each parameter (e.g., item codes for sec_8k, topic for polymarket_edge, series_id for fred_series) and explaining delivery channels with HMAC signing and phone verification.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource pair, and it distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides explicit prerequisites (Pipeworx OAuth account), lists supported types with examples, and details delivery channels. It covers when to use the tool well, though it does not explicitly mention when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context about return structure (category-bucketed examples with tool shapes) and parameter behavior (omit for full spread, pass topic to focus). 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 moderately long but well-structured with synonyms, examples, and front-loaded key phrases. It could be slightly more concise, but every sentence serves a purpose.

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

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

Given the tool has one optional parameter and no output schema, the description is fully complete. It explains the return format (category-bucketed example questions with tool+argument shapes), usage scenarios, and how to focus using the topic parameter. 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 has 100% coverage with a description for the single parameter 'topic'. The description adds value by listing example values (finance, pharma, etc.) and explaining that omitting gives a cross-category spread. This goes beyond the schema description.

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

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

The description clearly states it is an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It distinguishes siblings by explicitly guiding to use it FIRST when the agent does not know what Pipeworx can do, and contrasts with meta-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?

The description provides explicit when-to-use instructions: '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 lists example user queries that trigger this tool. It does not explicitly state when not to use, but the guidance is clear enough.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds key behavioral details: the subscription is deactivated, not deleted, so historical events remain via recent_alerts. This enriches agent understanding.

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 convey purpose, ownership constraint, and deactivation behavior with no wasted words. Information is front-loaded.

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

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

For a tool with one required parameter and no output schema, the description fully explains behavior, side effects, and constraints, making it sufficient for an agent to use correctly.

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

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

The schema already covers the single parameter with description 'Subscription id (uuid) returned by subscribe.' The description adds 'by id' but does not provide additional semantic value beyond the schema.

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

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

The description clearly states 'Cancel a subscription by id' with the specific verb 'cancel' and resource 'subscription', and distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

Provides explicit guideline: 'Ownership is enforced — you can only cancel your own subscriptions.' This tells the agent when it's appropriate to use the tool and implicitly warns against attempting to cancel others' subscriptions.

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

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

The annotations already signal read-only, open-world, idempotent, non-destructive behavior. The description goes far beyond this by detailing the internal pipeline (SEC EDGAR/XBRL fast path vs. grounded pipeline), the exact return semantics with six verdict types, and the critical distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source exists). This adds substantial context that annotations do not 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?

Despite being long, every sentence serves a purpose: trigger phrases, usage context, pipeline explanation, return values, and caller warnings. The structure is front-loaded with examples, then behavior, then nuances. No fluff—each sentence either adds usage guidance, describes behavior, or clarifies edge cases.

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

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

For a complex verification tool with no output schema, the description fully covers return values (verdict list, actual value, citation, reasoning), the two processing paths, and the subtle error semantics. It explains both 'could_not_verify' and 'unsupported' explicitly, and mentions the tolerance behavior. No critical details are missing for an agent to invoke and interpret results correctly.

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

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

The schema covers both parameters with descriptions, so baseline is 3. The description adds meaningful guidance, especially for tolerance_pct: it explains how to override the implied default, recommends 1–2 for hallucination detection, and notes the default cap of 5. This extra detail earns a 4, though the schema already carries most weight.

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 as verifying natural-language factual claims, using specific verbs like 'validate', 'verify', 'confirm or refute'. It distinguishes itself from generic search or Q&A tools by framing it as a claim-verification tool that returns a verdict and evidence, and explicitly mentions it replaces multi-step sequential calls.

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

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

The description states explicitly when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives concrete trigger examples and explains the two distinct pathways (company-financial vs. any other factual claim), and warns about the meaning of 'could_not_verify'. It positions itself as a replacement for a chain of calls, which provides implicit alternative guidance.

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