Yc Rejection

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

Builds on annotations by detailing return format (per-model scores, combined view) and BYO key behavior for Anthropic. Adds value beyond the readOnlyHint and idempotentHint 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?

Four concise sentences with front-loaded main action. Every sentence adds value: purpose, default behavior, extended usage, and return format. 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?

Without an output schema, the description sufficiently describes return structure. Covers all parameters and use cases. No gaps given the tool's complexity and 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 covers all 4 parameters (100%). Description adds clarity on default model, _apiKey pass-through, and context disambiguation, complementing the schema effectively.

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 uses a specific verb (probe) and resource (LLMs for business/brand/product/topic visibility), clearly differentiating from sibling tools like ask_pipeworx (Q&A) or scan_competitor_ai_presence. Includes default model and optional Anthropic integration.

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

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

States clear use cases (marketing audits, pre-launch checks, monitoring) and explains when _apiKey is needed. Could be improved by explicitly mentioning when not to use or comparing with siblings like scan_competitor_ai_presence.

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 readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds meaningful context beyond annotations: routing behavior, argument-filling, stable citation URIs, and tier compatibility, without contradicting 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 information-dense, front-loaded with 'PREFER OVER WEB SEARCH' and structured into domains, triggers, examples, and fallback guidance. Some redundancy exists ('START HERE' and 'default entry point'), but it remains well-organized and 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?

No output schema exists, yet the description explains the return format (structured answer with pipeworx:// citation URIs). It covers domain coverage, example queries, tier compatibility, and when to escalate to siblings, making it fully contextualized for the tool's complexity.

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

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

Schema has 100% coverage for all 6 parameters (one logical 'question' plus five aliases), each with descriptions. The description provides usage examples but does not add new parameter semantics beyond what the schema already specifies, so the baseline of 3 is appropriate.

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

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

The description clearly states it answers factual questions by routing to 5,529 tools across 1,455 sources and returning structured answers with citations. It uses a specific verb and resource, and explicitly contrasts itself with sibling tools like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

Provides explicit 'PREFER OVER WEB SEARCH' guidance, trigger phrases ('what is', 'look up', 'find'), and concrete examples. It also names specific alternatives: ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions, and clarifies breaking news is already handled.

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 (readOnly, openWorld, idempotent, non-destructive) are supplemented with substantial behavioral detail: identical toolset and arguments, live candidate routing, current inactive state, no fallback, and full functionality. This goes well beyond the annotation hints and accurately sets expectations.

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 information-dense, front-loaded with the key beta relationship and current status. Each sentence adds value—scope, live behavior, usage instruction, and a final reassurance that it is fully functional. Slightly verbose with specific counts, but not wasteful.

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 lack of an output schema, the description does not detail return values beyond 'same response shape' as ask_pipeworx, which is a minor gap. However, it covers purpose, status, usage context, and current equivalence to stable, making it sufficiently complete for an agent navigating experimental versus stable routing options.

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

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

The input schema has 100% description coverage and clearly documents the single required 'question' parameter plus five aliases. The tool description adds no parameter-level semantics beyond what the schema already provides, so the baseline score of 3 applies.

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, a universal router with the same 5,529 tools and response shape, but with experimental routing improvements. It distinguishes itself from the stable sibling ask_pipeworx by its 'experimental edge' and live candidate testing.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies current behavior (no active candidate means it matches stable) and that results are compared against stable. It does not explicitly exclude use cases or mention alternatives like ask_pipeworx_grounded, but the intended 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses the output structure with fields like evidence, confidence, and refusal_reason on success, and enumerates all refusal reasons on failure. It also states the extra cost and that only tool result content is used, providing rich behavioral context.

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

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

The description is dense but well-structured: purpose first, then mechanism, output format, refusal modes, usage guidance, and cost. It is longer than minimal, but every sentence adds necessary information for correct tool selection; it is appropriately 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?

With no output schema, the description fully explains return values and refusal handling. It covers purpose, mechanism, exact output fields, failure modes, cost, and when to use alternatives. This is complete for a tool of moderate complexity and high-stakes usage.

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

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

The schema already documents the question parameter and aliases with 100% coverage. The description does not add parameter-level syntax but does explain that the question is used to route to the right tool. This meets the baseline for high schema coverage without further parameter detail.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and differentiates it from ask_pipeworx by describing its grounded extraction and explicit refusal behavior. It specifies the exact function: routes to a data tool, fetches data, and extracts the answer using only the tool result.

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 provides when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also states the alternative: 'prefer ask_pipeworx for casual lookups,' and mentions the extra LLM call cost, giving clear decision criteria.

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 details behavioral traits beyond annotations: fan-out logic, response shapes, resolver contract (confidence levels, alternatives, suggestions), parent event extraction, news fields with fallback handling, safety short-circuits for low-confidence matches and closed markets, wide-spread warnings, and cancellation rule parsing. This far exceeds the minimal annotation set (readOnlyHint, openWorldHint, etc.).

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 comprehensive but overly verbose, running multiple long paragraphs. While the structure uses section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the main purpose, it could be more concise. Every sentence adds value, but the length may overwhelm some agents.

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

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

Despite lacking an output schema, the description thoroughly explains all return fields: market details, analysis (including edge calculations and 24h-move warnings), evidence structure, resolver contract, parent event, news fields with fallback info, and safety indicators. No important aspect is omitted.

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

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

Schema coverage is 100% (all 3 parameters described). The description adds value by explaining input types with examples, depth parameter defaults, and include_raw behavior with size implications. While the schema already covers basics, the description provides practical usage context.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison), and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on single bet research.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly contrast with sibling tools or specify when not to use it, though the context implies it's for individual bet research.

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 that indicate read-only, open-world, and idempotent behavior, the description details that the tool makes a single parallel call, sorts results by primary metric, and returns paired data with citation URIs. It also explains how financial data is sourced (latest 10-K, handling off-calendar fiscal years), which is valuable context not captured by 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 front-loaded with trigger phrases and examples. Every sentence contributes value, though it could be slightly more concise. The structure is logical: first trigger examples, then usage guidance, then data details.

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

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

Given no output schema, the description adequately covers purpose, usage, behavioral details, parameter semantics, and result characteristics (sorted, citations). It explains data sources for both entity types and mentions sorting behavior. No additional information seems necessary for an agent to correctly invoke the tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches these by providing concrete examples (tickers/CIKs for company, drug names for drug) and clarifies that values array should contain 2-5 items. This adds meaningful context beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses specific verbs and provides example queries, effectively distinguishing it from sibling tools like entity_profile which likely do single-entity lookups.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use this tool. It also explains the data sources for company and drug types, but does not explicitly state when not to use or mention alternatives beyond single lookups.

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

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

Beyond annotations (readOnly/openWorld/idempotent), it discloses account/auth requirements (GitHub signup, paid plan for thorough), expected latency (15-60s, thorough up to 90s), return packet structure (gaps[], contradictions[], citation_uri), and behavior quirks (semantic excerpting, never invented). No contradiction with annotations.

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

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

The description is a long single paragraph (~250 words) with dense, front-loaded details, starting with account requirement and core function. Every sentence carries useful information, but the format lacks structure (no bullets/line breaks) and repeats some depth details already in the schema, so not maximally concise.

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

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

Given no output schema, the description fully covers return values ('findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation', gaps[], contradictions[], hop field, citation_uri) and operational context (auth, latency, depth behavior). It answers all likely questions an agent would have about invoking this tool correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds operational depth: depth semantics ('standard re-angles unanswered gaps', 'thorough chases leads') and latency/payment implications, which go beyond the schema's enum descriptions. It clarifies that question should be natural language and broad/multi-part, adding value over 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call. It explicitly distinguishes itself from siblings ('this is NOT open-web search') and contrasts with ask_pipeworx for single lookups, so the purpose is unmistakable.

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

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

It provides explicit when-to-use/when-not: 'Best for broad/multi-part questions over structured data', and for a single lookup or breaking news prefer ask_pipeworx. It also notes account requirement and that unsigned users should use ask_pipeworx, giving clear alternatives and exclusions.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by detailing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations without any contradiction.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by usage context, examples, and output details. Every sentence adds value, no fluff. Approximately 5-6 sentences, efficient and well-structured.

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

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

Although there is no output schema, the description fully explains what the tool returns: tool names, descriptions, full input schemas with curated examples, and that they are ready to call. This is sufficient for a discovery tool with low complexity and 100% schema coverage for parameters.

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

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

Schema description coverage is 100% (all 6 parameters have descriptions). The description reinforces that 'query' is the main parameter and accepts aliases (task, q, description, search). It adds minor value over the schema by explaining the parameter purpose in context, justifying a score slightly above the baseline of 3.

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

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

The description clearly states the verb 'find tools' and specifies the resource 'by describing the data or task'. It lists many example domains (SEC filings, financials, etc.), distinguishing it from sibling tools that are specific data tools like ai_visibility_check or ask_pipeworx. The name 'discover_tools' matches the purpose.

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

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

Explicitly states when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also gives context: 'Use when you need to browse, search, look up, or discover what tools exist'. Provides clear usage direction.

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, non-destructive annotations, the description details that it fans across multiple sources, soft-fails for patents, and lists return fields, adding substantial behavioral context.

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

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

The description is effectively front-loaded with the purpose and main guidance. While it is somewhat lengthy, every sentence adds necessary detail, avoiding fluff.

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

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

For a tool with no output schema, the description comprehensively explains inputs, what data is returned (cik, filings, fundamentals, patents with note on status, news, LEI), and which sources are used, leaving little ambiguity for an agent.

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

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

Schema coverage is 100% and parameters are well-described, but the description adds extra context: value must be ticker or zero-padded CIK, names not supported, reinforcing usage constraints 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 a 'full cross-source profile of a US public company in ONE parallel call,' with specific sources and outputs listed. It distinguishes itself from chaining single-source lookups and mentions alternative tools like resolve_entity for names.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and instructs to use resolve_entity if only a name is available, providing clear when and when-not to use.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds the pairing context and deletion behavior, which is consistent. No additional behavioral details (e.g., error handling for missing keys) are given, but the description aligns with annotations.

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

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

Two sentences, no redundant words. The action and usage are front-loaded, and every sentence adds value. Efficient and clear.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and relationships to sibling tools. No gaps remain.

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

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

Schema coverage is 100%, and the description of the 'key' parameter ('Memory key to delete') matches the schema description exactly. No additional semantic information is provided beyond what the schema offers.

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

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

The description clearly states the action 'Delete' and the resource 'previously stored memory by key'. It distinguishes from sibling tools like 'remember' and 'recall' by specifying the delete operation, which is unique among the memory-related tools.

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

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

The description provides explicit when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also pairs with related tools 'remember and recall', offering contextual guidance 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: fetches page, extracts title/description/key links, emits standard markdown. There is no contradiction. However, it omits details like error handling or rate limits, but given the annotation coverage, this is acceptable.

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

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

The description is three sentences, front-loaded with purpose and format, followed by process and use cases. No redundant words. Slightly more compact could improve it, but it's well-structured.

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

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

Given 2 params and no output schema, the description explains the output format (standard llms.txt markdown, single text blob) and mentions source extraction. Missing details like error handling or URL validation, but for a straightforward generation tool with good annotations, it's fairly complete.

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

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

Schema description coverage is 100% for both parameters (url and max_links). The description does not add parameter-specific details beyond the schema, which is acceptable. The baseline of 3 applies because the schema already documents the parameters well.

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 to help AI crawlers index sites. The verb 'generate' and resource 'llms.txt' are specific, and the purpose (AI indexing) is explicit. Among siblings like scan_competitor_ai_presence, this tool is distinct.

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 concrete use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. While it doesn't explicitly state when not to use or compare to alternatives, the context is clear and sufficient for most scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool's safety profile is well-covered. The description adds value by listing return fields (id, type, params, etc.), which is helpful given no output schema. However, it doesn't disclose potential limitations like pagination or rate limits, so it's adequate but not outstanding.

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 only two sentences. The first sentence directly states purpose and output, and the second provides usage guidance. Every word serves a purpose, with no wasted text. It is 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 read-only tool with one optional parameter, the description covers all needed aspects: what it does, what it returns, and when to use it. Error handling or edge cases are not critical due to the tool's simplicity and the annotations indicating safe operation. The description is 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?

With 100% schema coverage and only one boolean parameter ('include_inactive'), the schema already explains the parameter well. The description adds the context that 'active' is the default, reinforcing the schema's description. This is sufficient but not exceptional beyond 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 'List the caller's active subscriptions' with a specific verb and resource. It also lists the return fields, making the tool's function unambiguous. It implicitly distinguishes from siblings like 'subscribe' and 'unsubscribe' by indicating use for review before adding or finding IDs to cancel.

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 includes explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool. However, it does not explicitly state when not to use it or name alternative tools, though the context with sibling tools is clear.

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

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

The description adds valuable behavioral context beyond the annotations: it discloses the rate limit (5 per identifier per day), that it does not count against tool-call quota, that filing without an account returns a claim_token for later follow-up, and that the team reads digests daily. This goes well beyond the sparse annotations (which only indicate non-read-only, non-idempotent, non-destructive) and paints a clear picture of the tool's side effects and constraints.

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?

While the description is long, every sentence earns its place: it establishes purpose, gives use cases, excludes non-Pipeworx tools, explains token mechanics, notes rate limits, and clarifies cost/quota implications. The structure is front-loaded with the main action and progressively adds operational details without redundancy.

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

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

The tool is fully specified despite having no output schema: the description explains both filing feedback and how to retrieve the resolution via claim_token. It covers prerequisites (identifying Pipeworx tools, not pasting end-user prompts), behavioral limits (rate limiting, quota exemption), and the human workflow (daily digests, roadmap impact). For a feedback tool with this complexity, nothing critical is omitted.

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

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

The input schema already provides complete descriptions for all four parameters (100% coverage), so the description carries less burden. However, it adds meaningful operational semantics for the claim_token parameter, explaining that it should be passed alone to read previous feedback status, and it clarifies that context is optional structured data. This slightly elevates it above the baseline 3.

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

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

The description opens with the specific action 'Tell the Pipeworx team something is broken, missing, or needs to exist,' making the tool's purpose immediately clear. It distinguishes itself from sibling research/entity tools by explicitly focusing on feedback about Pipeworx tools themselves, and it defines the feedback categories (bug, feature, data_gap, praise) with concrete examples.

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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: tools from other MCP servers should not be reported here, and explains how to identify Pipeworx tools. The claim_token usage is also explicitly instructed.

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 valuable behavioral context: data from CF analytics-engine, no PII, and caching duration (5min-1h depending on window). No contradictions.

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

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

Description is concise and well-structured with bullet points for use cases. Every sentence adds value, and there is no unnecessary information.

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

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

Given one parameter, no output schema, and thorough annotations, the description covers the return content (top tools, top packs, total call volume) and caching behavior, making it complete for the tool's simplicity.

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

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

Schema coverage is 100% with the 'window' parameter documented via enum. The description adds meaning by explaining that shorter windows surface what's hot right now while longer windows show steady-state demand, going beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, using specific verbs and resources. It distinguishes from siblings like 'ask_pipeworx' by focusing on trending usage data.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tools, checking alignment with agent needs). This guides when to use the tool, though it does not explicitly state when not to use it.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: internal logic (semantic anchor, partition filter, fill check), no modification, and response structure. No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear sections (modes, filters, response fields). It is front-loaded with the main purpose. Minor redundancy could be trimmed, but detail is justified by complexity.

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

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

Despite no output schema, the description thoroughly explains response fields (opportunities array, partition_check, fill_check details). It covers edge cases (cross-event, placeholder filtering, fill-check caveats) and provides comprehensive guidance for a complex tool.

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

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

Schema coverage is 100%, but the description adds extensive meaning beyond the schema, including recommended usage, examples, and detailed behavior for each parameter (event slug, topic query, no-args fallback).

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from siblings by specifying its unique function and methods.

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 on when to use each mode (no args for trending scan, event for single-event, topic for cross-event) and includes a fill-check caution against trading if book liquidity insufficient. However, it does not directly compare to sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description is highly transparent, detailing the three model segments, edge calculation, slippage, caching, and diagnostics. 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?

While front-loaded with purpose, the description is very long and dives into deep technical details about each model family. It is structured but could be more concise without losing essential information.

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

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

Given the complexity (9 parameters, no output schema, three model segments), the description is exceptionally complete. It explains caching, Fed bet exclusion, diagnostics for empty segments, and all knob usage.

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

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

Schema coverage is 100% with detailed descriptions. The tool description adds valuable context beyond the schema, such as explaining the effect of min_partition_leg_kelly on partition opportunities and the tradeable-edge knobs, earning above baseline.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It identifies the purpose as helping decide 'what should I bet on today' and distinguishes itself from paging hundreds of markets.

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

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

The description provides explicit guidance that the tool is for discovering opportunities without paging. It mentions that Fed bets are excluded from ranking and explains when to use knobs like min_liquidity. However, it does not directly compare with sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior, which the description reinforces by stating it reads snapshots. The description adds important behavioral details: decay calculation from daily closes, data gaps due to cache-miss days, and the expiration logic for opportunities that disappeared. 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 relatively long but well-structured, starting with the core purpose and then detailing response fields and limitations. Every sentence adds value, though some technical details could be streamlined for brevity. The front-loading is effective.

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

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

Given the absence of an output schema, the description comprehensively covers the return values: `tracked[]`, `expired[]`, and `snapshot_dates[]`, explaining key fields like `trend`, `decay_pp_per_day`, and `lifespan_days`. It also addresses limitations and data gaps, making the tool's capabilities and constraints fully understandable.

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

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

The input schema already describes the two parameters with defaults and ranges (100% coverage). The description adds context for `days` (lookback, default 14, max 30) and `window` (snapshot family, default '1wk'), but does not elaborate beyond what the schema provides. It also explains the response structure, which compensates slightly for the lack of an output 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 specifies the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers specific questions about edge age and decay, distinguishing it from sibling tool polymarket_edges, which likely just lists raw edges.

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

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

The description states when to use the tool (to determine how long an edge has existed and if it is shrinking) and implies when not to use it (for intraday data, as decay is from daily closes). It also mentions limitations like the 60-day snapshot TTL, but does not explicitly list alternative tools.

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

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

Annotations confirm readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds behavioral context like walking the order book, returning specific fields, and flagging thin legs and forced directional risk, enhancing 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?

Description is detailed but well-structured with clear separation of single-market and basket modes, and uses bold keywords (SINGLE-MARKET, BASKET) for readability. Could be slightly more concise, but maintains efficiency.

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 enumerates all return fields for both modes, explains the verdict system, and covers usage context thoroughly, making it fully actionable.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by explaining default values, mode-dependent interpretations (size_usd for buys vs sells), and auto-detection for side in basket mode.

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 realizable-vs-theoretical edge check against live CLOB order-book depth, specifying two distinct modes (single-market and basket) with explicit verbs and resources.

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 (before acting on arbitrage signals or trades above ~$500) and why theoretical overround on thin books is not capturable, and warns about partial basket fills causing directional risk.

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 confirm read-only, idempotent, non-destructive. The description adds rich behavioral detail: compatibility_warning conditions, temporal alignment, skipped cross types, and the likelihood of meaningless spreads. No contradiction with annotations.

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

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

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. While dense, every sentence adds value; minor redundancy could be trimmed.

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

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

No output schema, but the description fully explains the response structure (leg prices, top_spreads_pp, safety fields) and caveats (temporal alignment, compatibility). Complete for an information 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%. The description elaborates on each parameter: topic lists the 10 shortcuts, and explicit tickers are illustrated with examples. It also clarifies override behavior.

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

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

The description explicitly states it computes cross-venue spread between Kalshi and Polymarket for the same question. It distinguishes from siblings by focusing on multi-venue comparison and explaining two modes (topic shortcuts and explicit tickers).

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

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

It explains when to use each mode and warns that pre-mapped topics often yield compatibility warnings, implying alternatives like manual tickers. However, it does not explicitly contrast with siblings like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds scoping details (identifier types) and behavior when key is omitted, adding value 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?

Three sentences, no waste. Front-loaded with the primary action, then usage guidance and scoping. Efficient and well-structured.

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

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

Given low complexity (1 optional param, no output schema), the description fully explains core functionality, scoping, and pairing with remember/forget. Complete and sufficient.

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

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

With 100% schema description coverage, baseline is 3. The description restates that omitting the key lists all keys, which is already in the schema. No 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 the tool retrieves a stored value or lists all keys, with specific verbs and resource. It distinguishes from siblings like 'remember' and 'forget' by calling out pairing.

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

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

The description says to use it for looking up stored context without re-deriving, providing clear usage context. It does not explicitly state when not to use or list alternatives, but the context is strong.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral details like the mark_read flag affecting subsequent calls and the return structure (source, citation_uri, payload).

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 purpose, and each sentence adds value. No unnecessary words.

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

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

Given the five parameters and no output schema, the description covers main behavior, parameters, and usage tips. It could mention pagination or the list format, but it's sufficient for a read-only polling 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, baseline is 3. The description adds meaning by explaining the effect of mark_read (flag events read), filter by type and since, and mentions limit implicitly. It 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 states the tool pulls fired events from the subscription feed and returns recent alerts. It uses specific verbs and resources, distinguishing it from siblings like recall or search_within.

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

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

The description mentions that polls work fine and provides an alternative access method, offering some usage guidance. However, it does not explicitly compare to sibling tools or state when not to use it.

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

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

Describes fan-out to multiple sources (SEC, GDELT/GNews fallback, USPTO soft-fail), explains the return structure ('changes grouped by source + total_changes + pipeworx:// URIs'), and details the `since` parameter behavior. Adds significant context beyond the annotations (readOnlyHint, idempotentHint, etc.).

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 a clear overall purpose, but it is a single dense paragraph. Could be broken into sections for readability, though every sentence serves a function with minimal 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?

Without an output schema, the description still explains the return format (grouped changes, counts, URIs) and covers edge cases (GNews fallback, USPTO soft-fail). Combined with sibling distinction and parameter details, it provides all needed context for correct invocation.

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

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

Schema coverage is 100% with basic descriptions, but the tool description enriches by explaining accepted formats for `since` (ISO date vs relative shorthand with examples) and clarifying that `value` can be a ticker or zero-padded CIK. Adds non-obvious nuance.

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+resource: 'change feed for a company' with concrete query examples ('What's new with X', 'latest on Y'), and distinguishes itself from the sibling tool 'entity_profile' by stating when to use the other instead.

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 contrasts with 'entity_profile' for static profiles, and provides contextualized usage through examples like 'updates on Acme'. Gives clear direction on when to choose this tool over an 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?

Adds behavioral details beyond annotations: key-value scoping, persistence differences for authenticated vs. anonymous users (24-hour retention). 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?

Four sentences, front-loaded with purpose, every sentence adds value (use cases, scoping, sibling references). No waste.

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

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

Complete for a simple store tool: covers usage, behavior, scoping, and sibling pairing. Lacks return value description, but acceptable given no output schema.

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

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

Schema covers 100% of parameters with descriptions; the tool description adds no additional parameter-level meaning, so 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?

Description clearly states the tool saves data for reuse across sessions, with specific verb (save) and resource (data). It distinguishes from siblings recall and forget by mentioning them explicitly.

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 clear when-to-use examples (resolved ticker, user preference) and mentions pairing with recall/forget, but does not explicitly state when not to use it.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses critical behavior: graceful degradation (GLEIF/OpenFIGI unavailability), multi-endpoint cascading, source labeling, and explicit reporting of unresolved identifiers. This gives the agent a clear model of what happens during execution.

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

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

The description is fairly long but well-structured, leading with example queries, then usage guidance, then detailed type-specific behavior. Every sentence adds functional value, though it could be tightened without losing information. It earns a 4 rather than 5 due to some redundancy (e.g., repeated enumeration of identifiers).

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

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

Given the complexity of the tool (multiple identifier sources, nested ownership, enrichment fallback) and no output schema, the description remarkably covers return values, failure modes, and data provenance. It tells the agent exactly what to expect, including how unresolved IDs are handled, making it complete for reliable 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 the schema already describes both parameters well (100% coverage), the description adds semantic depth by explaining the value formats for each entity type (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company, and 'brand or generic name' for drug). It also explains what identifiers each type resolves, which is valuable context beyond the schema.

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

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

The description explicitly states the tool resolves user-spoken names to canonical identifiers (CIK, LEI, FIGI, RxCUI) and gives concrete query examples. It clearly differentiates from siblings by positioning it as the 'FIRST' tool to use when you have a name but need an ID, making its purpose unmistakable.

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

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

The description provides strong usage guidance ('Use FIRST whenever you have a name but need an ID') and clarifies supported types and input formats. However, it does not explicitly mention when not to use it or list alternative tools, which would have pushed it to a 5.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral details: it calls ai_visibility_check for each entity, ranks results, and returns a list with score, confidence, and signal density. This goes beyond annotations by explaining the operational flow and output format.

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

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

The description is concise at 4 sentences. It front-loads the primary action and then efficiently adds details on process, use case, and output. Every sentence contributes unique information without redundancy.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description covers the core functionality, output format, and relationship to sibling tools. It lacks details on error handling or edge cases, but for a simple comparison tool, it is sufficiently complete. Annotations already cover safety aspects.

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 descriptions cover all 4 parameters (100% coverage), so baseline is 3. The description adds value by explaining that the first entity in entities is treated as the 'subject' for narrative and that omitting models defaults to workers-ai. This provides semantic hints not present in the schema.

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

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

The description clearly states the verb 'Compare' and the resource 'AI visibility across multiple entities'. It specifies the process: probes each entity with ai_visibility_check, ranks by score, and surfaces the most/least recognized. The usage example further clarifies the purpose, distinguishing it from the sibling ai_visibility_check tool which handles single 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 clear context for when to use the tool: 'Useful for competitive AI-marketing audits' and gives a concrete example. It implies that this tool is for comparing multiple entities, while the sibling ai_visibility_check is for single entities. However, it does not explicitly state when not to use this tool or list alternative tools for specific scenarios.

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

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

Discloses critical runtime behavior beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed will include timeouts. Annotations already mark as read-only and idempotent, and description adds complementary detail 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?

Dense and informative; first sentence captures core composite check, then details follow. Slightly long but every sentence adds value. Could be trimmed slightly, but still effective.

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

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

Despite no output schema, description completely enumerates return fields (summary block, per-advisory detail, links, alternative versions) and partial failure behavior. Covers all essential information for a complex external data aggregation tool.

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

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

Schema covers both parameters with 100% description coverage. Description adds context that version defaults to latest and that scoped packages are accepted, which is helpful but not essential beyond the schema.

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

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

Description clearly states the tool is a composite check for evaluating npm packages across deps.dev and bundlephobia. It uses specific verbs ('fan out','returns') and identifies the exact question it answers ('should I add this npm package to my project'). Distinct from siblings like scan_competitor_ai_presence.

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

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

Explicitly tells when to use ('when agent asks is X safe/popular/small or what does adding lodash cost') and when not to ('PyPI/Maven/Cargo/Go fall under deps.dev:version directly'). Provides clear context for decision-making.

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

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

Beyond annotations (read-only, idempotent), the description discloses embedding model (BGE-base-en), similarity metric (cosine), windowing strategy (500-char overlapping), character limit (200K with truncation flag), and output format (passages with offsets, scores). No contradiction with annotations.

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

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

The description is a single paragraph but packs essential information efficiently. It is front-loaded with the core purpose and uses clear language. Minor structure improvements (e.g., bullets) could help, but it remains concise.

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

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

Given the complexity and no output schema, the description fully covers how the tool works, its limits, output format, and usage context. It also mentions pairing with a sibling, making it complete for agent understanding.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value with natural-language query examples, clarifies the truncation behavior, and explains output structure, slightly exceeding the schema's information.

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

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

The description clearly states the tool does semantic search inside a fetched record, using a specific verb and resource. It distinguishes from siblings by mentioning it pairs with ask_pipeworx_grounded and contrasts with direct fetch for large texts.

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: when the record is too big to cram into the prompt, and explains the benefit of saving context. Provides pairing guidance with ask_pipeworx_grounded and gives example queries, making usage 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 provide readOnlyHint=false and idempotentHint=true, but description adds significant behavioral context: OAuth requirement, non-persistence for anonymous, delivery channel constraints (SMS cap, phone verification, webhook auto-disable). However, idempotency hint is not elaborated.

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 well-structured starting with purpose, then return value, requirements, types, and delivery. It is slightly lengthy but every sentence adds value. Could be more concise by listing examples, 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?

For a complex tool with multiple types and delivery options, the description is comprehensive: covers account requirement, type-specific params, delivery constraints, and important behavioral details (webhook secret one-time, auto-disable). No gaps for correct usage.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining each subscription type with examples, delivery options with validation rules, and constraints (e.g., phone must be verified, SMS cap). This goes beyond the schema's literal descriptions.

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

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

Description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription id. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and the specific types enumerated.

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

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

Provides context on when to use (to setup monitoring) and prerequisites (requires Pipeworx OAuth account). Does not explicitly state when not to use or contrast with siblings, but the context is sufficient for correct selection.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context about the output format and that it draws from a live catalog, providing transparency beyond annotations.

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

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

The description is lengthy but well-structured, front-loading the purpose and using bullet-style listing of topics. Every sentence adds value, though some redundancy exists with the 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?

Despite no output schema, the description fully explains the return value (category-bucketed examples with tool details), parameter behavior, and use case. It is complete for an onboarding 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?

The schema coverage is 100% and the description doesn't add significant meaning beyond the schema's description of the topic parameter. The schema already lists the allowed values and usage.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx by focusing on suggesting questions rather than answering them.

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 when to use this tool: '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 mentions passing a topic to focus and lists alternatives (ask_pipeworx, entity_profile, etc.).

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

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

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This adds value beyond annotations, which already indicate non-destructive and idempotent behavior.

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

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

Two focused sentences with no waste. The first sentence states the action, the second covers behavioral details. 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 single-parameter tool with no output schema, the description sufficiently covers purpose, usage constraint, and behavioral nuance. 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?

The parameter 'id' is described as 'Subscription id (uuid) returned by subscribe.' with 100% schema coverage. The description adds useful context linking it to the sibling tool 'subscribe', helping the agent know where to obtain the ID.

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 the specific verb 'Cancel' and noun 'subscription', clearly indicating the action and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by being the inverse operation.

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 the ownership constraint: 'you can only cancel your own subscriptions.' This provides clear context for when to use. Could be improved by mentioning when not to use, but it's sufficient.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds critical failure semantics: could_not_verify means the check did not happen and carries verification_error{stage,detail}, must not be shown as evidence; unsupported means no source coverage. It also enumerates the full verdict list and explains the two execution paths, going well beyond annotations.

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

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

The description is front-loaded with trigger examples and a clear purpose sentence, then efficiently covers the two execution paths, return structure, a critical callers caveat, and efficiency context. Every sentence serves a purpose with no filler or redundancy.

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

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

With no output schema, the description assumes full responsibility for describing return values: it lists all six verdicts, explains the edge cases (could_not_verify vs unsupported), and mentions the citation and reasoning. Given the tool's two pipeline complexity and the presence of detailed annotations, the description is complete enough for an agent to select and invoke 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?

The input schema provides 100% coverage with detailed descriptions for both parameters, including tolerance_pct's range, semantics, and default. The tool description adds no additional parameter-specific meaning beyond what the schema already provides, so the 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 opens with natural-language examples and explicitly defines the tool as 'natural-language claim verification against authoritative sources.' It clearly identifies the action (verify/check), the resource (factual claims), and scope, and distinguishes itself by mentioning it replaces 4–6 sequential calls, differentiating it from lookup/research 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?

'Use whenever the agent needs to check whether something a user said is factually correct' provides explicit when-to-use guidance. It also describes the two processing paths (SEC EDGAR fast path vs grounded pipeline) and clarifies that could_not_verify is not evidence, which informs correct handling. However, it does not name sibling tools or give explicit when-not-to-use scenarios.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate a safe, read-only, and idempotent tool. The description adds that encouragement is not sincere, but does not elaborate on behavioral traits like output format or statelessness. With strong annotations, the description adds minimal value.

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 that front-load the core purpose and add a quirky detail. Every word earns its place; no redundancy or superfluous content.

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

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

Despite having an output schema (not shown), the description does not mention the return value structure. With 6 parameters and no parameter explanations, the tool definition is incomplete for effective use, even though the core functionality is clear.

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

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

The input schema has 6 parameters with 0% description coverage, and the tool description does not explain any of them. The only clue is 'startup idea', which maps to the required 'idea' parameter, but optional parameters (e.g., traction, pivot_count) remain entirely undocumented.

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

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

The description clearly states the verb 'generate' and the resource 'YC rejection', with the object 'startup idea'. It succinctly distinguishes from sibling research tools, making its humorous purpose unmistakable.

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

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

No explicit guidance on when to use versus alternatives is provided. The description implies it's for generating a rejection with encouragement, but lacks any context about appropriate scenarios or warnings that it's not a real rejection.

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