Producthunt

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

Annotations already mark as readOnly, idempotent, non-destructive. The description adds value by disclosing default model pricing, that Anthropic calls are billed separately, and the output structure (per-model data + combined view). No contradictions.

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

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

Two sentences, front-loaded with the main action, no fluff. Every part adds value: what it does, default model, optional Anhtropic usage, return format, and use cases.

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

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

Despite no output schema, the description fully documents return format (per-model {score, confidence, signals, raw_response} + combined view). All 4 parameters are explained with usage context, making it self-sufficient 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%, so baseline is 3. The description adds meaning by explaining default model selection, that _apiKey is only needed for anthropic, and that context disambiguates entities, which goes beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for brand visibility and scores it 0-100 per model. It specifies verb 'Probe' and resource 'LLMs for business/brand/product/topic', effectively differentiating from siblings like deep_research or 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?

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use Anthropic model (BYO key). It lacks explicit exclusion conditions or direct alternatives, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds useful behavioral context: routing to sub-tools, filling arguments, stable pipeworx:// citation URIs, one fast call, and live news handling. Does not contradict annotations.

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

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

Description is longer than necessary but well-organized: starts with a clear preference directive, then covers scope, examples, escalation paths, and caveat about news. Each sentence contributes, though some repetition exists ('START HERE', 'default entry point').

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 flagship tool with no output schema and many siblings, the description covers purpose, when-to-use, alternatives, examples, routing behavior, citation format, tier compatibility, and speed. It is sufficiently complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with all parameters described as aliases for the question. Description only repeats the 'natural language question' concept and gives examples, which are also in the schema. No additional parameter details beyond what schema already provides.

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

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

Description clearly states it routes questions to the right of 5,529 tools and returns structured answers with citations, and it distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives. The verb 'asks' or 'routes' is specific and resource is well-defined.

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

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

Provides explicit use guidance: 'PREFER OVER WEB SEARCH', 'START HERE', and 'Step up only when needed' with named alternatives (ask_pipeworx_grounded, deep_research). Includes trigger phrases and examples, clearly stating when to use this tool versus others.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond this: it may change behavior when candidates are under test, currently matches ask_pipeworx because no candidate is active, and explicitly clarifies it is not a fallback but a full router. No contradictions with annotations.

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

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

Three sentences, all dense with relevant detail: equivalence to ask_pipeworx, experimental status, current state, and comparison purpose. No filler, though the specific number of tools (5,529) could be seen as extra. Still, it is well-structured and front-loaded.

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

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

There is no output schema, but the description covers the response shape ('same response shape'), current behavior, experimental nature, and relationship to the stable router. It is complete for such a tool, though it relies on the sibling ask_pipeworx for detailed return semantics.

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

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

Schema coverage is 100% with all parameters (including six aliases) documented, so the description need not repeat them. The baseline of 3 applies because the schema carries the full meaning; the description adds no additional parameter insight, but none is needed given the thorough schema.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with a specific experimental role. It distinguishes itself from the stable sibling by noting 'identical universal router' but 'candidate routing improvements enabled live' and 'this IS a full working router, just the experimental edge.'

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the comparison purpose against the stable router and notes current equivalence since no candidate is active, giving clear context for choosing this over ask_pipeworx.

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 (readOnly, openWorld, idempotent), the description discloses key behaviors: it returns structured evidence, lists specific refusal reasons, and admits the tool may refuse if data doesn't directly answer. It also notes the extra LLM call overhead, which is unannotated but critical 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?

Though long, every sentence is dense and useful: definition, routing behavior, return shape, refusal reasons, use cases, and cost comparison. The key selling point is front-loaded, and there is zero filler.

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 compensates by fully specifying the success return shape and all refusal reason enum values. It also explains the tool's routing across 5,529 tools and 1,455 sources, making the context complete for an agent to select and invoke accurately.

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%, with all parameters documented as aliases for the natural-language question. The description does not add new parameter-level meaning, but the schema fully handles it, 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 clearly identifies the tool as a 'hallucination-resistant answer mode' that routes like ask_pipeworx but extracts answers solely from tool results. It explicitly distinguishes from its sibling by describing the unique grounded extraction and refusal behavior, making the purpose specific and unambiguous.

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

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

Provides explicit use cases: 'Use whenever an answer will be quoted, cited, or acted on' and contrasts with ask_pipeworx for 'casual lookups.' The cost trade-off ('Costs one extra LLM call') gives clear when-to-use vs. when-not-to-use guidance.

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

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

The description exhaustively covers behavior beyond annotations (readOnlyHint etc.): resolver contract, parent event extractor, news fallback, safety short-circuits, closed market handling, wide spread notes, and cancellation rules. No contradictions with annotations.

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

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

The description is long but well-structured with capitalized sections (e.g., 'RESOLVER CONTRACT', 'SAFETY'), front-loading the purpose and usage. Every sentence provides necessary detail for a complex tool; minor verbosity is justified given the tool's sophistication.

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 comprehensively details response shapes (market, analysis, evidence), edge cases (low-confidence, closed markets, wide spreads), and resolution risk. It covers all necessary context for an agent to use the tool correctly and interpret results.

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

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

Schema coverage is 100%, but the description adds value by clarifying that 'market' can be a slug, URL, or question text, explains 'depth' enum with defaults, and details 'include_raw' trade-offs. While schema already documents parameters, the description enhances usability.

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 researches a Polymarket bet by pulling Pipeworx data, supporting multiple input formats (slug, URL, question text). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by targeting research for 'should I bet on X' queries.

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

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

Explicitly specifies use cases ('should I bet on X') and classifiers. Provides detailed guidance on interpreting results, including warnings about resolution confidence and the need to inspect market_match fields. Missing explicit 'when not to use', but the positive guidance is strong enough.

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

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

The description adds extensive behavioral context beyond annotations: it details data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), explains handling of off-calendar fiscal years, notes sorting by primary metric, and mentions citation URIs. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph that starts with example queries, clearly states purpose, and sequentially adds details. Every sentence provides necessary 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 no output schema, the description briefly mentions return value (paired data + citation URIs). For a complex multi-entity comparison tool, slightly more detail on output structure could help, but overall it is adequate.

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

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

Schema coverage is 100%, and the description adds value by explaining the format of values (tickers/CIKs for company, drug names) and why each parameter is used. This goes beyond the minimal schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, specifying data sources and metrics for each type. It distinguishes from siblings like entity_profile by emphasizing it replaces 8-15 sequential 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 advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example query patterns. It implies alternatives (entity_profile for single entities) but does not explicitly list 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?

Even with readOnlyHint/openWorldHint/idempotentHint annotations, the description adds substantial behavioral context: account/paid-tier requirements, decomposition into facets routed in parallel, return packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] for unanswered facets, semantic excerpting of large records, and expected latency ranges. This goes far beyond the annotations.

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

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

The description is long but each sentence carries useful information—authenticity, distinction from open-web, alternates, depth semantics, citation guarantees, and latency. It is front-loaded with account requirements and the core function. Could be slightly tightened by removing minor redundancy (e.g., repeated emphasis on structured data), but overall it remains purposeful and organized.

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

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

Given there is no output schema, the description fully specifies the return format (findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]) and behavioral edge cases (empty gaps for non-catalog topics, semantic excerpting, fetchable citations, latency expectations). The complexity of the tool (routing across 5,529 tools) is well addressed.

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 both parameters with 100% coverage, so the baseline is 3. The description adds value by detailing depth behavior (quick=3 facets, standard=5 with gap recovery, thorough=8 with follow-up and contradiction scan), the paid plan requirement for 'thorough', and clarifying that 'question' accepts broad/multi-part natural language questions.

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

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

The description clearly identifies the tool as 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources ... in ONE call' and explicitly contrasts it with open-web search. It distinguishes from siblings by positioning it for broad/multi-part structured-data questions and naming ask_pipeworx as the alternative for single lookups or current news.

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

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

Explicit when-to-use: 'Best for broad/multi-part questions over structured data' with concrete examples. When-not-to-use is given: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also states an account requirement and that ask_pipeworx works on every tier, making the choice conditional clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds key behavioral context: returns results with full schemas and curated examples, ready to call without a second lookup. No contradictions.

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

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

The description is a single paragraph but is well-organized: purpose first, then usage guidance, then return value. It is dense but could be slightly more structured (e.g., bullet points). Still, it's front-loaded and concise.

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

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

Despite no output schema, the description explains what the tool returns (top-N relevant tools with names, descriptions, and full input schemas with examples). This is sufficient for an agent to understand the output context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the main parameter accepts natural language and lists multiple aliases (task, q, description, search), which goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides a specific verb ('Find tools') and resource ('by describing the data or task'), and distinguishes itself from sibling tools by being the discovery/exploration tool.

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

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

Explicit usage guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it and implies when not (when you already know the tool).

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses that the USPTO component relies on a sunsetting API and will soft-fail, and explains the parallel fan-out across multiple datasources. 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 thorough and front-loaded with examples, but slightly lengthy. However, every sentence adds value, and the structure is logical with explicit sections for usage, returns, and limitations.

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

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

Given the tool's complexity (multi-source aggregation), no output schema, and no nested objects, the description fully explains what is returned, including specific fields, URIs, and fallback behavior. It also covers limitations (USPTO sunset, name unsupported) adequately.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaningful context: value can be ticker or zero-padded CIK, and type is limited to 'company' with a hint about future support. This adds value beyond the schema's baseline.

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

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

The description uses specific verbs ('research', 'brief me') and explicitly states 'full cross-source profile of a US public company', listing the integrated sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. It also distinguishes itself from siblings by advocating preference over chaining single-pack lookups.

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

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

The description provides explicit when-to-use guidance with examples like 'Tell me about X' and states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'. It also clearly advises using resolve_entity first if the user only has a name, as names are not supported.

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 and idempotentHint. Description confirms deletion but does not clarify behavior for missing keys or return values.

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 redundancy, front-loaded with action and resource.

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?

Sufficient for a 1-param tool; covers purpose and usage but not error scenarios or idempotency details.

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%. Description does not add extra meaning beyond the schema's parameter description.

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

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

Clear verb (Delete), resource (memory), and method (by key). Distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use (stale context, task done, clear sensitive data) and implies alternatives (pair with remember and recall).

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 safe read-only, idempotent, non-destructive behavior. The description adds valuable context: it fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions with annotations.

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

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

The description is a single paragraph with clear topic sentence followed by details. Every sentence adds value, but it could be slightly more structured with bullet points or separate sentences for use cases.

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

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

With no output schema, the description explains the output format ('single text blob') and file placement. All parameters are documented, no nested objects. The tool's behavior is fully described given its simplicity and the comprehensive 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% with descriptions for both parameters. The description adds meaning beyond schema by stating max_links default (25) and maximum (50), and clarifies url as 'Full URL of the site to summarize' including example.

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

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

The description uses specific verbs (generate, fetches, extracts, emits) and identifies the exact resource (llms.txt file). It clearly distinguishes the tool's purpose from sibling tools by specifying use cases for AI crawler indexing.

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 (client indexing, personal drafting, competitor auditing) and mentions the output destination (site-root/llms.txt). It lacks explicit when-not-to-use instructions but the sibling list shows no overlapping functionality.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns full details including specific fields, and provides an example call. No contradictions with annotations.

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

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

Two sentences plus an example. Front-loaded with purpose. No wasted words. Example is useful for understanding parameter usage.

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 get tool with 2 params, no output schema, and rich annotations, the description covers purpose, usage context, example, and return fields. It is complete and requires no additional explanation.

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

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

Schema coverage is 100% and already describes both parameters. Description adds a concrete example and clarifies slug origin, but doesn't significantly enhance parameter understanding beyond what schema provides.

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

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

Description clearly states 'Get full details for a single Product Hunt launch by its slug' and lists what's included: description, makers, topics, vote/comment counts. It distinguishes itself from sibling 'top_launches' by specifying this is for diving into a specific launch.

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

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

Explicitly says 'Use after top_launches to dig into a specific new product / startup launch.' This provides clear context on when to use. No alternatives or when-not-to are mentioned, but the guidance is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as true/false. The description adds value by specifying the returned fields and implying active subscription filtering, with no contradiction.

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

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

Two sentences with no wasted words: first explains purpose and output, second gives usage guidance. Well-structured and front-loaded.

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

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

For a simple tool with one optional parameter and rich annotations, the description adequately covers the return fields and usage. No output schema exists, but the field list is provided.

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

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

Schema description coverage is 100% for the single parameter include_inactive, which is fully documented. The description adds no extra parameter info, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates the returned fields (id, type, etc.). This is a specific verb+resource, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly advises using this tool to review monitored subscriptions before adding more or to find an id for cancellation, providing clear context for when 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 provide only false hints (readOnly, destructive, idempotent), so the description carries the burden. It discloses rate limits ('5 per identifier per day'), the claim_token workflow (returned on filing and usable to check status later), operational details (free, no quota), and content rules (don't paste end-user prompt). This goes well beyond the annotations.

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

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

The description is long but front-loaded with purpose and every sentence adds value (use cases, exclusion, token mechanism, rate limits). No filler, though it could be slightly tighter; still appropriately sized for the 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?

With no output schema, the description thoroughly covers return semantics (claim_token), follow-up reading, rate limiting, and scope. For a feedback tool with four parameters, this is complete and self-contained.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds extra guidance on how to use claim_token (example call) and constraints on message content (describe in terms of Pipeworx tools/packs, don't paste user's prompt), raising it to 4.

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

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

The description clearly states the tool's function with a specific verb and resource ('Tell the Pipeworx team'), and enumerates use cases (bug, feature/data_gap, praise). It distinguishes from siblings like ask_pipeworx by being the sole feedback channel.

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 specifies when to use (broken/stale data, missing capability, praise) and when not to (tools from other MCP servers), with an alternative ('file it with that server instead'). It also clarifies scope to this Pipeworx connection and offers a heuristic for identification.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds specifics: 'self-aggregating signal', 'no PII', 'cached 5min-1h depending on window', and data source (CF analytics-engine). No contradictions.

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

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

Three sentences plus three bullet points, all relevant. Front-loaded with key purpose. No redundant 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?

Despite no output schema, description covers return value (top tools/packs, total call volume) and caching behavior. Complete for a simple read-only tool with one parameter.

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?

Single parameter with full schema coverage. Main description restates window options but does not add meaning beyond the schema description. 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?

Clearly states it returns top tools/packs and call volume from other AI agents on Pipeworx. Distinguishes from sibling tools like ask_pipeworx (Q&A) and discover_tools (general discovery).

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 three explicit use cases (discovering hot data sources, confirming canonical tool, seeing alignment). Does not explicitly state when not to use, but context is clear with sibling names.

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 and idempotentHint, and the description adds substantial behavioral context: scanning process, partition checks, similarity thresholds, placeholder filters, and fill check logic. No contradiction.

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

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

The description is comprehensive but somewhat verbose; it could be slightly more concise. However, it is well-organized and front-loaded with the core purpose.

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

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

No output schema, but the description fully explains the response structure (opportunities, partition_check, fill_check), covers edge cases (low similarity, placeholder filters), and provides trading guidance. Complete for such 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?

Both parameters are fully described in the schema, and the description adds extensive context: event slug examples, topic seed question examples, and detailed explanations of how each mode works.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes from siblings by being specific to Polymarket arbitrage and detailing the mechanisms.

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

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

It explicitly explains when to use each call mode (no args for trending, event for specific market, topic for cross-event), including when to use event over topic, and provides examples.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds that the tool caches results at the KV level for 1 hour, excluding Fed bets from ranking due to unreliable signals, which provides valuable behavioral context beyond annotations.

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

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

The description is verbose with multiple paragraphs and technical details on model families. While front-loaded with a clear purpose, it could be more concise. The structure uses headings and lists but the length may overwhelm an agent.

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

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

Despite having no output schema, the description covers the response structure (by_segment, fed_candidates, _diagnostics) and explains what each opportunity contains (edge_pp_net, kelly_fraction, etc.). With 9 parameters fully described in schema, the tool description is comprehensive for the task.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context beyond schema, such as explaining tradeable-edge knobs (min_liquidity, max_spread_pp) in context and providing practical guidance (e.g., 'Polymarket has zero trading fees...' and 'Bump for very thin partitions'), which enhances parameter understanding.

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

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

The description clearly states the verb (scan, return) and resource (top Polymarket markets) with a specific purpose: find opportunities where Pipeworx data disagrees with market price. It distinguishes itself from sibling tools like polymarket_arbitrage by being built for 'what should I bet on today' and avoiding paging through 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 extensive guidance on when to use this tool (discovering betting opportunities) and includes tradeable-edge knobs for filtering, but does not explicitly state when not to use it or directly compare to alternative tools. The sibling list implies alternatives, but explicit guidance is missing.

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, open-world, idempotent, non-destructive behavior. Description adds critical behavioral contexts: data sourced from daily snapshots with 60-day TTL, decay computed from daily closes not intraday, and response includes tracked, expired, and snapshot dates. No contradictions with annotations.

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

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

Description is thorough but somewhat lengthy. It is front-loaded with the core question and response structure is clearly explained. Every sentence contributes to understanding, but could be slightly more concise without losing 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 no output schema, description comprehensively explains the response format (tracked, expired, snapshot_dates) with field semantics. It also covers data provenance, limitations (60-day TTL), and decay computation details. No gaps for effective use.

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

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

Schema covers both parameters with descriptions, but description adds meaningful context: default values for days and window, explanation of window as 'snapshot family', and implicit constraints (max 30 days). This adds value beyond the schema definitions.

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 specifies the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It explicitly contrasts with raw edge data by focusing on temporal analysis ('how long has this edge existed and is it shrinking?'). This distinguishes it from sibling tools like polymarket_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?

Usage context is implied but not explicitly stated. The description indicates it is for assessing edge persistence, and the response structure suggests analysis of opportunities over time. However, it does not provide explicit guidance on when to use this tool versus alternatives like polymarket_edges or direct scenario comparisons.

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 safety profile (readOnlyHint, idempotentHint, non-destructive). Description adds behavioral details: parameter requirements, return fields (verdict, forced_directional_risk), and mode behavior. No contradiction.

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

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

Description is somewhat lengthy with multiple paragraphs, but well-structured by mode (single-market vs basket). Front-loads key purpose. Could be more concise by referencing schema, but the detail aids comprehension.

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, description comprehensively lists return fields for both modes. Covers edge cases (thin legs, partial fills, forced directional risk). Combined with annotations, it provides complete context for agent to use tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning beyond schema: explains auto-detection of side for basket, size_usd interpretation as settlement notional, and default values. Provides context for each parameter.

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

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

Description clearly states tool performs 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by being a risk-check before trades.

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

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

Explicitly tells agent to use this before any polymarket_arbitrage or polymarket_edges trades above ~$500, warns of unhedged directional position risk, and explains when single-market vs basket mode is appropriate.

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: explains response structure (price objects, top_spreads_pp), safety fields (compatibility_warning conditions, temporal_alignment meaning, skipped counters), and notes when spreads are meaningless (aligned:false). This adds significant context to the generic annotations (readOnlyHint, openWorldHint, idempotentHint).

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-organized with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence provides necessary detail; there is no fluff. It could be slightly more concise, but the structure aids readability.

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

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

Given the complexity (cross-venue, multiple parameters, safety warnings) and lack of output schema, the description covers essential aspects: modes, response fields, compatibility conditions, and temporal alignment. It does not cover error handling or rate limits, but for a read-only idempotent tool this is acceptable.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by listing the 10 topic macros, explaining that tickers override topic, and clarifying usage. It builds on the schema without redundancy.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It outlines two modes (topic shortcuts and explicit tickers) and distinguishes it from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons.

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

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

The description provides explicit guidance on when to use each mode, including a warning that most pre-mapped topics return compatibility_warning and that 'real cross-venue spreads are rarer than the macro-shortcut list suggests.' It implies that for reliable spreads, explicit tickers should be used. However, it does not explicitly state when not to use the tool or compare with other siblings beyond this.

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 description does not need to repeat those. The description adds scoping detail ('anonymous IP, BYO key hash, or account ID') which is useful but not extensive. It does not contradict annotations.

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

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

The description is relatively concise with three sentences, each adding value. It front-loads the main action and then provides context. Could be slightly tighter (e.g., combine first two sentences) but is effective overall.

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

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

Given the low complexity (1 optional parameter, fully described schema, and informative annotations), the description adequately covers retrieval and listing behavior. No output schema exists, but the description implies the return type (value or list). It is complete enough for correct tool selection and 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% and includes a description for the key parameter. The description adds the crucial behavior that omitting the key lists all saved keys, which is not in the schema description and adds meaningful value beyond the structured data.

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 states the specific verb ('Retrieve' or 'list') and resource ('value previously saved' or 'all saved keys'). It explicitly distinguishes from the sibling tools remember and forget by naming them, making it clear what recall does relative to its companions.

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

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

Description says to use it for looking up stored context without re-deriving, which provides a clear when-to-use. It also mentions scoping and pairing with remember/forget. However, it does not explicitly state when not to use or compare to other possible alternatives (e.g., search tools).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about the returned data (source, citation_uri, payload) and explains the mark_read behavior ('so the next call only shows newer ones'), which goes beyond the annotations.

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

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

The description is three sentences long, front-loaded with the purpose, and every sentence provides useful information without redundancy. It is appropriately concise for a tool with 5 parameters.

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

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

The description covers the key return fields (source, citation_uri, payload) and mentions an external endpoint for alternative access. With no output schema, this is sufficient. It could be slightly enhanced with pagination hints, but the limit parameter addresses that.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds semantic value by explaining the effect of mark_read on subsequent calls and confirming that since expects an ISO timestamp, but it does not add significant meaning beyond the parameter descriptions.

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

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

The description starts with 'Pull fired events from your subscription feed', using a specific verb and clearly indicating the resource. It distinguishes this tool from siblings like list_subscriptions by focusing on retrieving events from the feed.

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 'Polls work fine' and provides an alternative external endpoint for scripts/dashboards. It explains filtering by type and since, but does not explicitly state when not to use this tool or compare with other siblings beyond the external option.

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 reveals fan-out to SEC, GDELT→GNews fallback, USPTO soft-fail, and output 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?

Single dense paragraph is well-structured, front-loaded with example queries, then function, sources, input, output. Every sentence adds value.

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

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

Given no output schema, the description adequately describes return format (changes[], total_changes, citation URIs). Covers sources, fallback, and parameters completely.

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

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

Schema coverage is 100%, but description adds examples and recommendations for 'since' (e.g., '30d' for monitoring) and explains 'value' as ticker or CIK, enriching meaning beyond schema.

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

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

The description explicitly states it provides a 'change feed for a company in the last N days/weeks/months' with examples like 'what's new with X'. It distinguishes from sibling 'entity_profile' by noting that tool is for static profiles.

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 clear when-to-use examples (e.g., 'latest on Y', 'updates on Acme') and explicitly says to use 'entity_profile' instead for static profiles, providing 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?

Annotations indicate idempotentHint=true, which the description complements by stating storage is scoped by identifier and has a 24-hour retention for anonymous sessions. It adds context about persistence for authenticated users and the key-value nature, going beyond annotations without contradicting them.

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

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

The description is composed of concise sentences, each serving a distinct purpose: defining the action, providing usage guidance, and noting behavioral caveats. It is front-loaded with the core purpose and avoids any 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?

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description is thoroughly complete. It covers what the tool does, when to use it, how it behaves (scoping, retention), and how it relates to sibling tools. No additional context would meaningfully improve agent selection.

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 100% coverage with descriptive names and descriptions for both parameters. The description adds value by giving concrete examples of keys ('subject_property', 'target_ticker') and values ('findings, addresses, preferences'), enhancing the semantic understanding beyond the schema.

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

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

The description uses a specific verb ('Save') and resource ('data') and distinguishes the tool from siblings (recall, forget). It provides concrete examples of usage (ticker, address, preference) and clearly states the purpose: to store data for reuse across conversations or sessions.

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

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

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and contrasts it with related tools (recall, forget). It does not give explicit 'when not to use' guidance, but the context is clear enough for an agent to decide.

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

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

Beyond the read-only/idempotent annotations, it discloses that lookups cascade across multiple endpoints, degrade gracefully when external sources are unavailable, and that unresolved identifiers are explicitly listed rather than omitted. This adds valuable 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 long but well-structured, with examples, core purpose, type details, and fallback behavior. It is front-loaded with the core use case and each section adds value, though some example utterances could be trimmed.

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

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

For a complex lookup tool without an output schema, it thoroughly documents inputs, outputs, supported types, and edge-case behavior. It leaves no major ambiguity for an agent deciding to invoke it.

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

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

The schema already covers both parameters at 100% coverage, so baseline is 3. The description adds meaning by explaining what identifiers are returned for each type and accepted input formats, going beyond the schema descriptions.

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

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

The description clearly states the tool resolves user-spoken names to official identifiers, with specific examples and supported entity types. It distinguishes itself from siblings by being the go-to for name-to-ID lookups ('Use FIRST').

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 to use first when you have a name but need an ID, and lists supported entity types. It doesn't provide when-not-to-use guidance or alternative tool names, but the use case 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 significant behavioral context beyond annotations: it explains the underlying process (probing with ai_visibility_check, ranking), output details (ranked list with score, confidence, signal density), and the role of the first entity as subject. No contradictions with annotations.

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

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

The description is concise (4 sentences) and well-structured: action, process, use case, output. 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 lack of an output schema, the description adequately describes the return format (ranked list with fields). It covers the essential behavior and use case. Minor omission: no mention of error handling or limits beyond schema, but schema covers entity count bound (2-8).

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

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

Schema description coverage is 100%, so the description adds little beyond the schema. It does mention that the first entity is treated as subject, which adds marginal value, but overall parameter semantics are already well covered by schema.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side. It specifies the verb 'Compare' and the resource 'AI visibility across multiple entities'. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI presence and ranking.

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 frames usage for competitive AI-marketing audits and provides an example question. It implies when to use (multi-entity comparison) but does not explicitly state when not to use or mention alternatives like ai_visibility_check for single entities. This is slightly lacking.

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

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

Annotations already provide readOnly, openWorld, idempotent hints. Description adds critical details: partial failures, bundlephobia timeout (5-30s), sources_failed field, and graceful degradation. 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?

Three sentences, each adding value. Could be slightly tighter (e.g., merge first two sentences), but front-loaded with main purpose and uses bullet-like listing of checks.

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 thoroughly explains return content (summary block, advisories, links, alternatives). Covers edge cases (timeout, NPM-only) and behavioral nuances. Fully meets complexity needs.

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

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

Schema covers both parameters (100% coverage). Description adds context: scoped packages accepted ("@types/node"), default version is latest, and implies package name is required.

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

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

The description clearly states it's a composite check for npm packages covering deps.dev and bundlephobia. It lists specific checks (license, advisories, bundle size, etc.) and differentiates from siblings by being a single-call aggregation.

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: 'whenever an agent asks "is X safe / popular / small"'. Also notes NPM-only in v1 and points to alternative deps.dev:version for other ecosystems.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant technical details: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), character cap (200K chars with truncation flag). No contradiction with annotations.

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

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

Single paragraph that front-loads the core purpose, then efficiently covers usage, pairing, and technical details. Every sentence is informative, no redundancy.

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

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

With no output schema, the description explains the output (top-N passages with offsets and similarity scores) and the ability to verify quotes. All parameters are described, and the tool's behavior is fully covered.

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 3 parameters have descriptions). The description adds extra context: examples for query, default and range for limit, and clarifies text's max length and the meaning of offsets.

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

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

The description uses specific verbs and resources ("Semantic search INSIDE a fetched record") and provides concrete examples (SEC 10-K, article). It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: "Use when the record is too big to cram into the prompt." It explains the benefit (saves context, returns only relevant passages with offsets) and mentions an alternative or complementary tool.

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

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

The description adds significant behavioral context beyond annotations: subscription creation is not read-only, requires OAuth, returns an ID, and has limitations (phone verification, SMS cap, webhook auto-disable). However, it does not discuss idempotency, though annotations indicate idempotentHint=true. No contradiction.

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

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

The description is comprehensive but somewhat lengthy; however, information is well-organized with bullet-like lists and examples. Every sentence adds value, but could be slightly more concise.

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

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

Given the complexity of multiple subscription types and delivery channels, the description is complete. It covers requirements, limitations, examples, and return value (subscription ID). No output schema exists, but the description adequately explains the output.

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

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

Schema coverage is 100%, and the description adds substantial meaning: it explains type-specific params with examples, delivery options with rules (e.g., webhook signing secret, phone verification, SMS cap). This greatly surpasses the schema's minimal parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb (create) and identifies the resource (subscription). It also lists supported types, distinguishing it from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

The description explains when to use the tool (proactive monitoring), the required authentication (Pipeworx OAuth account), and details for each subscription type. It lacks an explicit exclusion of when not to use, but provides ample context for correct usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the safety profile is clear. The description adds useful behavioral context: the tool is the onboarding entry point and returns example questions with tool calls. It does not describe rate limits or auth needs, but those are not relevant for a read-only tool. The description complements annotations well.

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 every sentence serves a purpose: it provides example user queries, explains the return format, gives invocation instructions, and positions the tool relative to siblings. It could be slightly tighter, but the front-loading with common questions is effective for agent understanding.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers all necessary aspects: purpose, usage, parameters, return value, and relationship to sibling tools. It tells the agent exactly what to expect and how to use it. No gaps remain.

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

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

Schema coverage is 100%, so the schema already describes the topic parameter. The description adds value by explaining that omitting the topic gives a 'cross-category spread' and enumerating the exact allowed values (finance, pharma, etc.), giving more context than the schema's enum list.

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

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

The description clearly states the tool returns category-bucketed example questions with tool+argument shape, explicitly positioning it as the onboarding entry point. It distinguishes itself from sibling tools like ask_pipeworx and deep_research by advising 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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

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

The description provides explicit when-to-use guidance ('Use this FIRST'), includes two invocation patterns (no arguments vs. with topic), and lists alternative tools such as ask_pipeworx, entity_profile, and compare_entities. It clearly states what the tool is for and when to prefer it.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds value by listing specific return fields (name, tagline, votes, etc.) and providing an example call, enhancing 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?

Description is concise (3 sentences plus example) and front-loaded with key purpose. However, the example is repeated in both description and schema examples, slightly redundant.

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

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

No output schema, but description lists return fields. For a simple read tool with well-documented parameters and annotations, the description is sufficiently complete to guide agent 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 clear descriptions. Description reinforces meaning with an example call and explains order enum values (RANKING, VOTES, NEWEST) and their defaults, adding context beyond schema.

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

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

Description clearly states the tool retrieves 'today's and recent top Product Hunt launches', specifies it's for new product/startup launches, lists return fields, and distinguishes itself from unrelated sibling 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?

Description explains when to use (to see launches, trending products) but does not explicitly state when not to use or provide alternatives. However, given sibling tools are unrelated, the guidance is clear enough.

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

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

Discloses beyond annotations: the row is deactivated (not deleted) and historical events remain available via recent_alerts. Annotations (destructiveHint=false, idempotentHint=true) are consistent and enriched.

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: first states action and constraint, second explains outcome. No filler, front-loaded with key information.

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

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

For a simple tool with one parameter, the description covers purpose, ownership, and effect. Output schema absent but not needed. Sibling tools are available but relationships are 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?

Single 'id' parameter is fully described in schema (100% coverage). Description adds that the id is returned by subscribe, providing helpful provenance beyond schema.

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

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

The description uses a clear verb 'cancel' and resource 'subscription by id', distinguishing it from the sibling tool 'subscribe'. It concisely states the action and scope.

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

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

Explicitly mentions ownership enforcement, guiding agents to use only for their own subscriptions. Does not explicitly list alternatives, but the context of siblings (subscribe, list_subscriptions) is implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral detail: it explains the two routing paths, the exact verdict types, the citation format, and the crucial distinction between could_not_verify (did not happen, not evidence) and unsupported (no source). This goes well beyond the annotations and provides essential nuance for an agent.

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

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

The description is longer than average but every sentence adds value. It is front-loaded with natural-language examples, flows logically through the two paths, return values, and error semantics. The 'IMPORTANT for callers' section is critical. It is not wasteful, though slightly verbose for a tool description.

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

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

With no output schema, the description carries the burden of explaining return values and it does thoroughly: verdict types, citation, reasoning, and error conditions. It also covers the routing logic and the distinction between error states. This is complete for a complex NL verification 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% for both parameters, so the schema fully documents claim and tolerance_pct. The description does not add additional parameter details beyond what the schema already provides. Baseline 3 is appropriate because the schema does the heavy lifting and the description does not need to compensate.

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 validates natural-language factual claims against authoritative sources, using verbs like 'verify', 'fact check', 'confirm or refute'. It differentiates from siblings by describing the dedicated SEC EDGAR + XBRL fast path and the fallback grounded pipeline, and explicitly says it replaces 4–6 sequential calls.

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

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

The description gives explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims and other claims, and warns about the could_not_verify vs unsupported semantics. However, it does not explicitly name alternative tools or state when not to use it, though the 'replaces 4–6 sequential calls' hints at alternatives.

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