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 cover read-only, non-destructive, open-world, and idempotent behavior. The description adds useful behavioral context beyond the schema: it discloses that the tool dynamically selects among thousands of tools, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is long but densely informative: it front-loads the most important guidance, gives concrete examples, and then provides routing alternatives. Minor redundancy exists—such as the self-referential 'single focused question... use ask_pipeworx' line—but overall every section earns its place.

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

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

Given that there is no output schema, the description adequately explains what the tool returns: a structured answer with stable citation URIs. It also covers trigger phrases, domain coverage, examples, and when to use sibling tools, making it complete enough for an agent to invoke the tool correctly in most scenarios.

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 fully documents the 'question' parameter and its aliases. The description provides natural-language examples and usage triggers, but it does not add parameter-level detail beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: it routes natural-language factual questions to one of thousands of verified data tools and returns structured answers with stable citation URIs. It also differentiates itself from web search and names sibling tools, so an agent can identify when this tool is the right choice.

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

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

The description gives explicit usage conditions: prefer over web search, use for queries starting with 'what is', 'look up', 'find', 'get the latest', 'how much', or factual questions about real-world entities. It also names alternatives such as ask_pipeworx_grounded, ask_pipeworx_beta, and deep_research, with concrete conditions for choosing them.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context: beta status, live candidate routing, the current state of no active candidate, and the fact that this is not a fallback stub but a fully working router. It could disclose more about potential instability, but it is transparent enough.

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 beta relationship and quickly establishes the current operational state. It is a bit detailed with specifics like the 5,798 tools and the retirement date, but these details reinforce the beta status and do not feel excessive.

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

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

With no output schema, the description usefully states that the response shape matches ask_pipeworx and clearly indicates the tool is not a stub. The required question parameter and aliases are covered by the schema. It relies somewhat on the agent knowing ask_pipeworx, but that is reasonable given the sibling context.

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

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

Schema coverage is 100%, so parameters and aliases are already documented. The description adds only that it shares the same arguments as ask_pipeworx, which is helpful for cross-tool consistency but does not deepen the meaning of the question parameter. A baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx and states it is a full universal router with the same 5,798 tools. It also draws the key distinction from the stable tool: candidate routing improvements are enabled when under test, and it should be used 'when you want the newest routing.'

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

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

The description explicitly tells the agent when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also adds that results are compared against the stable router and that when no candidate is active it matches ask_pipeworx exactly, which prevents misuse and sets expectations.

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 readOnly/openWorld/idempotent annotations, the description richly discloses behavioral traits: it routes through the same tool-selection process as ask_pipeworx, extracts only from fetched data, returns an explicit refusal with specific reasons when no direct answer exists, and costs an extra LLM call. This far exceeds what annotations alone convey and contradicts nothing.

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 efficient, front-loading the core purpose and then systematically covering output shape, refusal reasons, use cases, and cost trade-off. Every sentence contributes actionable information, and the structure flows logically from what the tool does to when to use it.

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

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

Given the tool's complexity, the lack of an output schema, and the nuanced refusal logic, the description is complete: it specifies the exact success return shape, all refusal reasons, the single input's intent via schema, and real-world scenarios. An agent has enough to call it correctly and interpret its results without additional documentation.

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

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

Schema description coverage is 100%, so the schema already documents the 'question' parameter and its aliases. The description adds no further parameter-level meaning, but because the schema fully covers the single user-facing input, baseline 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant, grounded answer mode that extracts answers only from tool results. It explicitly differentiates from ask_pipeworx by describing the extraction constraint and refusal behavior, so an agent can distinguish it from siblings without opening schemas.

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

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

The description gives explicit when-to-use guidance: use when an answer will be quoted, cited, or acted on and facts must not be invented, with concrete domains like financial verdicts, legal claims, and medical lookups. It also states when not to use it — prefer ask_pipeworx for casual lookups — and names the sibling alternative.

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

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

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 only declare read-only/idempotent/non-destructive behavior; the description adds substantial operational context: account/tier requirements, parallel decomposition across 5,798 tools, explicit gaps[] for unanswered facets, contradictions[] for standard/thorough, citation_uri availability, semantic excerpting, and latency expectations. No statement contradicts the annotations.

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

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

The description is long but dense, with every sentence carrying operational value and the account requirement front-loaded. It could be tightened into clearer scannable bullets, but given the tool's complexity the length is not excessive.

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

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

With no output schema, the description fully specifies what comes back: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and latency ranges. Together with account/tier and usage routing, nothing an agent needs to decide whether and how to call it is missing.

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

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

Input schema covers both params 100%, and the description adds real meaning: question is 'natural language' and broad/multi-part is fine; depth values are expanded with quick=3 single-hop, standard=3 gap-recovery plus contradictions, thorough=6 paid iterative pass. This gives an agent enough to choose parameter values correctly.

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

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

The description states a specific action: grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and returning a findings packet. It explicitly says it is not open-web search, distinguishing it from broader search tools. It also names the sibling ask_pipeworx and the condition for using it, so the tool is unambiguous.

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

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

It gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples, and 'For a single lookup use ask_pipeworx instead.' It also covers the signed-out fallback condition. This routes the agent cleanly among deep_research, ask_pipeworx, and open-web search.

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?

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing key behaviors: parallel fan-out across multiple sources, soft-fail behavior for the USPTO API sunset, the expected-empty semantics of fda_products, and the resolved:false handling for private companies. It also explains that empty sections are real 'no data' conditions, not bugs.

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 dense and front-loaded with realistic query phrasings and then a structured list of returned fields. Some parameter and type guidance duplicates schema text, but the overall length is justified by the tool's complexity and the absence of an output schema.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: cik/company_name, recent_filings with URIs, fundamentals sorted by period_end DESC, patents, federal contracts, FDA products, hiring, news, LEI, and sources_used/sources_failed. Edge cases such as private companies and USPTO soft-fails are also covered, making the tool safely invokable.

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

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

Schema coverage is 100%, but the description adds helpful context by giving concrete examples for tickers, CIKs, and company names, and clarifying that names resolve via SEC EDGAR company-name matching. It also reinforces that 'company' and 'ticker' are interchangeable, though this largely echoes what the schema already states.

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 defines the tool as a 'full cross-source profile of a US public company in ONE parallel call' and gives concrete example queries. This makes it easy to distinguish from more targeted sibling tools by emphasizing the broad, holistic scope it covers.

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

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

It explicitly instructs agents to 'ALWAYS PREFER' this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. However, it does not explicitly name sibling tools like compare_entities or resolve_entity, nor does it spell out when-not-to-use cases, so the exclusions are implied rather than exhaustive.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's burden is behavioral context, which it delivers richly: compatibility_codes[] can be non-empty even when matched_pairs>0, temporal_alignment null means 'could not be computed,' legs with unknown metric_type are never paired, and every spread_pp is gross of Kalshi fees. It also discloses that pairings are keyword-based with pairing_unverified always set, which aligns with and extends the openWorldHint annotation.

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?

Long, but every sentence earns its place in a tool with a heavy caveat surface; CAPS section markers (TWO MODES, RESPONSE, SAFETY FIELDS) make it navigable and the core purpose is front-loaded in the first sentence. The repeated warnings ('read them even when matched_pairs>0', 'null means ..., not ...') each prevent a distinct misinterpretation rather than waste words.

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

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

With no output schema, the description must stand in for the return contract, and it does: leg-by-leg raw probabilities, top_spreads_pp, compatibility_warning/codes, temporal_alignment, fees_note, skipped counters, and low_confidence_pairs are all specified. For a 3-param optional tool with this many failure modes and no structured return definition, nothing an agent needs to correctly interpret results is missing.

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 schema already lists the topic enum values and states that the explicit ticker/slug 'Overrides the topic-mapped' side. The description adds that both modes run the identical token-overlap matcher so the same caveats apply, but this is marginal incremental meaning beyond the schema — baseline 3 is appropriate.

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

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

Opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' — a specific verb, resource, and scope in one sentence. It further pins down the semantics with the 'Kalshi − Polymarket' spread direction and the bet-shape equivalence caveat, leaving no ambiguity about what the tool computes versus edge/arbitrage siblings.

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

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

Clearly distinguishes the two invocation modes ('TWO MODES: (1) topic ... (2) explicit kalshi_event_ticker + polymarket_event_slug') and warns that 'pre-mapped ≠ tradeable' and most shortcuts return compatibility_warning today. It does not explicitly name alternatives such as polymarket_arbitrage, but the fees_note ('gross, not a net tradeable edge') implicitly tells agents not to use this for executable-edge calculations.

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?

Beyond the readOnly/idempotent/openWorld annotations, the description discloses graceful degradation when LEI/FIGI sources are unavailable, internal cascading across multiple lookups, explicit `unresolved` fields, and candidate-returning behavior on ambiguity. No contradiction exists with the annotations.

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

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

The description is front-loaded with query examples and the key usage directive, and almost every sentence adds value. It is on the long side with dense parentheticals, but the structure is organized enough that an agent can quickly extract the essential guidance.

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

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

With no output schema present, the description carries the full burden of explaining what the tool returns, and it does so thoroughly: CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand, unresolved identifiers, and candidate responses. An agent has enough context to invoke it correctly and interpret results without additional lookups.

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?

Even though schema coverage is 100%, the description adds substantial meaning: acceptable input forms (ticker, CIK, ISIN, name), entity-name-only instructions, the bond issuer exact-match caveat, and the difference between company vs drug resolution. It goes well beyond the schema's short property descriptions.

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

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

The description names a specific verb ('resolve') and resource (canonical/official identifiers), and reinforces it with realistic user phrasings and supported entity types. It clearly distinguishes itself from sibling tools by positioning it as the first step when a name is known but an ID is required.

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' and provides concrete input guidance for both supported types. It even warns against passing full noun phrases for bonds, which directly prevents invocation errors.

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

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

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.