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=true and idempotentHint=true, and the description adds useful behavioral context: it routes, fills arguments, and returns citation URIs rather than directly producing a static answer. This goes beyond what annotations alone communicate and does not contradict 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 opening guidance is useful and front-loaded, but the description contains a repeated "START HERE for most questions" block with the same examples appearing multiple times. This makes it unnecessarily long and not every sentence earns its place.

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

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

For a broad routing tool with rich annotations and full schema coverage, the description explains the output shape (structured answer with stable citation URIs), provides use cases and examples, and names alternatives. It could describe exact response fields, but that is not essential 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 description coverage is 100%, so the schema fully documents the question parameter and its aliases. The description reinforces that the input is a natural-language question and gives examples, but it does not add significant parameter-level meaning beyond the schema.

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

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

The description clearly states the tool's function: it routes a question to one of 5,743 tools across 1,500 verified sources, fills arguments, and returns a structured answer with pipeworx:// citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can identify which tool is which.

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

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

The description explicitly says to prefer this tool over web search for certain data categories and lists trigger phrases like "what is", "look up", "find", and "get the latest". It also gives clear guidance on when to step up to ask_pipeworx_grounded or deep_research, making the decision boundary explicit.

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

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

The description goes beyond the benign annotations by revealing the current experimental state: no candidate is active, so behavior currently matches ask_pipeworx exactly. It also clarifies that it falls back to nothing and is a full working router, not a stub or proxy. This is valuable behavioral context the annotations do not provide.

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

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

The description is front-loaded with the key fact that this is the beta version and wastes little space. It is slightly redundant in repeating that it is identical/same, but every sentence contributes useful information about current status, usage, and fallback behavior.

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 beta variant whose main job is routing, the description is complete enough: it explains the current parity with ask_pipeworx, the experimental nature, and how results are used. It does not spell out the response structure, but it points to the stable counterpart's response shape, which is adequate 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?

The input schema already provides 100% coverage, including clear descriptions for the question field and its aliases. The description adds no new parameter-level semantics beyond saying the arguments are the same as ask_pipeworx, which is sufficient but does not exceed the schema baseline.

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

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

The description clearly identifies this as a beta version of ask_pipeworx and states that it is an identical universal router with the same tools, arguments, and response shape. It also explicitly distinguishes it from the stable router by calling it the experimental edge, making its purpose unambiguous.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router and that no candidate is currently active, which directly informs when and why an agent should choose this tool.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral traits: it costs an extra LLM call, it refuses rather than fabricates, and it enumerates exact refusal reasons such as not_in_source, no_tool_match, tool_error, data_truncated, and llm_error. This gives an agent a precise mental model of success and failure behavior beyond what annotations convey.

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

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

The description is dense and front-loaded with purpose, then return contract, then usage guidance, then cost tradeoff. It is longer than minimal, but nearly every sentence adds real value: routing details, refusal behavior, use cases, and cost. It could be slightly tightened, but it is well-organized and not padded with fluff.

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

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

For a query tool with no output schema, the description fully covers the return shape, success and refusal cases, cost behavior, routing behavior, and when to use it over alternatives. The input schema handles parameter details, so nothing critical is missing for correct 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%, so the baseline is 3. The description does not add meaningful parameter semantics beyond the schema: it only says the question is in natural language, while the schema already describes aliases and natural-language behavior. No parameters are explained in more depth, but the schema is sufficient, so the score stays at 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 leads with a specific, informative purpose: a 'hallucination-resistant answer mode for high-stakes reads' that routes like ask_pipeworx but extracts answers only from tool results. It clearly distinguishes this grounded tool from the plain ask_pipeworx sibling, leaving no ambiguity about what the tool does or how it differs.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and the condition to prefer it: 'prefer ask_pipeworx for casual lookups.' This is model usage guidance that directly tells an agent how to choose between siblings.

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

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

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?

Annotations already cover read-only, open-world, idempotent, and non-destructive traits, so the description's additional disclosures go well beyond the bar: account/plan requirements, parallel decomposition, gap reporting with 'never invented', contradiction scans, timing expectations, semantic excerpting, and fetchable citation URIs. No contradiction with the annotations was found.

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?

Every sentence contributes substantive behavioral or routing information, and the most decision-critical caveats are front-loaded. However, the description is a dense single block with frequent semicolons, which makes it harder to scan quickly than a structured or shorter version would be.

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

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

With no output schema, the description carries the full burden of documenting the return value and edge cases, and it does so thoroughly: findings structure, verbatim evidence, confidence, source, fetched_at, gaps[], contradictions[], citation reachability, and latency. Given the tool's complexity, an agent has enough information to select it and call it correctly.

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

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

Input schema coverage is 100%, so the baseline is 3, but the description enriches both parameters: it explains what the depth levels actually do in the research flow (quick=3, standard=3 with gap recovery, thorough=6 paid with iterative chase) and confirms that the question parameter is meant for natural-language, multi-part queries. This adds practical selection guidance beyond the schema's enum text.

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?

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' in one call. It also explicitly distinguishes itself from open-web search and from ask_pipeworx, making the tool's role among siblings clear. The return artifact — a findings packet with citations and gaps — is also named.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and 'For a single lookup use ask_pipeworx instead.' It also names the alternative for signed-out users and explains depth-tier implications. This is concrete routing behavior, not vague context.

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?

The description goes far beyond the readOnly/openWorld/idempotent annotations by explaining the fan-out across many data sources, the sources_used/sources_failed mechanism, and that an empty section means real 'no data,' not a bug. It also discloses name resolution behavior and the expected behavior for small-molecule/generic-only companies.

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

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

The description is long but information-dense, with user-intent triggers front-loaded and no filler. Every sentence earns its place by conveying source details, return semantics, or important edge-case behavior that would otherwise be absent without an output schema.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: CIK, company name, resolution fields, filings, fundamentals, patents, contracts, FDA products, hiring, news, LEI, and source success/failure tracking. It is complete enough for an agent to understand what the tool returns and how to interpret 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?

Although the schema already covers both parameters fully, the description adds meaningful semantics: accepted value shapes (ticker, zero-padded CIK, or name), type interchangeability, resolved_from/resolved_to behavior, and the private-company failure mode. These details help an agent construct correct calls.

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 a specific verb and resource: it produces a full cross-source profile of a US public company in one call. It also distinguishes itself from an alternative approach ('chaining single-pack SEC/XBRL/news lookups') and from related use cases by noting 'person/place coming soon.'

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 says to prefer this tool when the user asks for a holistic view or says 'tell me about X,' and to prefer it over chaining multiple lookups. It also describes the when-not case: private companies resolve as false with an explicit notes line, not a bare failure.

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?

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: compatibility warnings/codes, token-overlap matching, fee grossness vs net edge, skipped-leg counters, and temporal alignment caveats. There is no contradiction with the annotations.

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

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

The description is long but dense and information-rich, with purpose front-loaded and critical safety disclosures clearly called out. Some structure via bullets or headings would improve scannability, but every sentence earns its place given the tool's complexity.

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

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

With no output schema, the description thoroughly explains the response shape: per-venue prices, `top_spreads_pp`, compatibility fields, per-entry flags, skipped/confidence buckets, temporal alignment object, fee note, and skipped-comparison counters. It also covers caveats such as `temporal_alignment_unknown` and unclassified legs being never paired, making the tool safely callable by an agent.

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

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

Schema coverage is 100% and each parameter already has a description. The tool description still adds meaning by explaining that `topic` auto-fetches a matching event on each venue, that explicit params override the topic-mapped side, and that both modes run the identical matcher. This is useful added context beyond the schema.

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

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

The opening sentence states the tool's precise function: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from the Polymarket-only sibling tools by naming both venues and the spread concept.

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 mode-selection guidance: use `topic` for 10 pre-mapped shortcuts and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. It also warns that pre-mapped topics are not necessarily tradeable. It does not explicitly name sibling tools as alternatives, so it stops short of a 5.

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

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

Annotations already 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, lowering the bar. The description adds valuable behavioral detail: ambiguous names return `figi_candidates` instead of asserting; unresolved identifiers are explicitly listed under `unresolved`; LEI/FIGI enrichment degrades gracefully when sources are down; and it returns a citation URI for drug lookups. No contradictions with annotations.

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

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

The description is front-loaded with query examples and the 'Use FIRST' directive, so the most important usage guidance appears early. The company-type parenthetical is a dense run-on sentence, but every clause carries crucial behavioral information (ambiguity handling, unresolved field, source labeling, ISIN-to-LEI mapping). It is verbose but justifiably so given the tool's complexity.

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

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

With no output schema, the description bears the burden of explaining return values, and it does: it mentions return of `figi_candidates`, `unresolved`, identifier-source labels, and for drugs lists RxCUI + ingredient + brand + citation. It covers all input types, edge cases (multiple matches, unavailable sources), and the internal cascade of lookups. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds critical semantics beyond the schema. For `value` it warns 'Pass the ENTITY NAME ONLY' and gives a detailed example about bond issuer names versus full noun phrases, explaining why trailing security-class words match nothing. For `type`, it enumerates what each enum value returns (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand). This significantly enhances agent 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 opens with a barrage of user-phrased queries ('What's the ticker for…', 'find the CIK for…') and then states the verb precisely: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This clearly distinguishes the tool from siblings like entity_profile or compare_entities, which focus on profile or comparison rather than name-to-ID resolution. The 'Use FIRST' directive and mention of replacing 2-3 manual lookups further cement its unique role.

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 says 'Use FIRST whenever you have a name but need an ID', which is a strong directive that applies before considering alternatives. It also gives concrete query examples and explains scope boundaries (e.g., covers non-US issuers EDGAR cannot reach). It does not name specific alternative tools or give explicit 'do not use when' conditions, so it misses the full 5, but the context is clear.

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

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

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.