Producthunt

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

Annotations already declare readOnlyHint and idempotentHint, so the tool is non-destructive and safe. The description adds important behavioral details: it probes multiple models, returns per-model scores with confidence/signals/raw_response, and discloses that Anthropic probing requires a BYO key with direct payment to Anthropic. This 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 two well-structured sentences. The first sentence front-loads the action, scoring function, and output. The second provides key usage details (default model, API key note). Every sentence adds value with 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?

Given the tool's complexity (4 parameters, probing multiple models) and no output schema, the description adequately explains return values: per-model fields (score, confidence, signals, raw_response) plus a combined view. It also explains optional parameters and their purpose, making the tool fully understandable.

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

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

Schema coverage is 100% (all parameters have descriptions). The description adds practical meaning: default model is Workers AI Llama-3.3-70b (free), *_apiKey* is only needed for Anthropic, and *context* helps disambiguate. This enriches the schema beyond basic 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 knowledge about an entity and scores visibility. The verb 'probe' and resource 'LLMs' are specific, and the use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) distinguish it from siblings like scan_competitor_ai_presence or compare_entities.

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

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

The description provides clear context for when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and mentions the default model and optional API key for Anthropic, guiding usage. However, it does not explicitly mention when not to use it or compare to alternatives, but the sibling list provides some 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, openWorldHint, idempotentHint, and non-destructive, but the description adds value by stating it returns structured answers with stable citation URIs and routes to the correct tool among 3,744 sources. No contradiction.

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

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

The description is front-loaded with key guidance and examples, but it is somewhat lengthy and includes redundant alias mentions. Still, every sentence adds value, earning a 4.

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 tool complexity (6 params, rich annotations), the description covers purpose, usage, and returns format. No output schema, but description mentions citations. Enough for an agent to invoke correctly.

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

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

Schema coverage is 100% with all parameters (including aliases) described. The description does not add meaning beyond the schema, but the schema itself is clear. 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 the tool's purpose: answering factual questions about current/historical data across many domains, with a verb 'ask' and resource 'Pipeworx'. It distinguishes from siblings by explicitly saying 'PREFER OVER WEB SEARCH' and mentioning routing to 3,744 tools, making it unique among 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?

Provides explicit when-to-use guidance: questions about SEC filings, FDA data, economic stats, etc. It lists trigger phrases like 'what is', 'look up', 'find', and gives concrete examples. It also implies when not to use by contrasting with web search, though no explicit exclusion. Strong guidance overall.

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

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

Describes refusal reasons (not_in_source, no_tool_match, etc.), response schema, and that it extracts answer only from tool results. Adds context beyond annotations (readOnlyHint, etc.) without contradiction.

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

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

Well-structured with key purpose front-loaded. Each sentence adds value, though slightly verbose with repeated routing description. Could be tightened but still effective.

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

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

Comprehensive given no output schema: includes response format, refusal reasons, cost, and usage guidance. Parameter schema fully covered. No gaps evident.

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

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

Schema coverage is 100% with all parameters as aliases. Description adds that 'question' accepts natural language and lists aliases, but this is already evident from schema descriptions. No additional 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?

Clearly states the tool's purpose: hallucination-resistant answer mode for high-stakes reads. Distinguishes from sibling ask_pipeworx by noting extra LLM call cost and use case.

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: when answer will be quoted/cited/acted on and invention of facts is unacceptable. Also advises preferring ask_pipeworx for casual lookups.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details beyond annotations: low-confidence resolutions short-circuit, dead markets return 'market_closed_or_inactive', wide-spread markets carry 'illiquid_wide_spread', resolution-rule risk parsing, news fallback mechanisms, and parent_event extraction. 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 extensive and dense, covering many details in a structured yet lengthy manner. It uses section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) but could be more concise. It earns its place but is not optimally succinct.

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

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

Given the complexity of the tool (no output schema, 3 parameters, many siblings), the description is exceptionally complete. It details response shapes, safety mechanisms, resolution rules, news fallbacks, and edge cases. Agents can use this description confidently.

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 for all three parameters. The description provides examples for market_input that align with the schema, and adds context for include_raw's impact on response size. Baseline is 3; description adds marginal value beyond schema.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, listing three input formats (slug, URL, question text). It distinguishes itself from sibling tools like ask_pipeworx or deep_research by focusing specifically on Polymarket bets with a structured research pipeline.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and includes classifier examples and fan-out examples. It does not explicitly state when not to use this tool, but the context makes it clear it is for bet decisions, hence a small gap.

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 safe, read-only, idempotent behavior. Description adds rich detail: data sources (SEC EDGAR/XBRL, FAERS), specific fields (revenue, net income, etc.), correct handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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 informative but relatively long; however every sentence adds value. Front-loaded with examples and usage patterns. Minor room for tightening.

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 and moderate complexity, the description covers what each type returns, ordering, and how it replaces many lookups. Lacks error handling details but annotations provide open-world hint. Generally complete.

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

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

Schema coverage is 100%; description adds meaning beyond schema by explaining the enum values ('company' vs 'drug') and providing concrete examples for the values array (tickers or drug names with limits). Also explains data returned for each type.

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 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call,' using specific verbs and resources. It distinguishes from sequential lookups and sibling tools like entity_profile.

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

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

Explicitly advises ALWAYS PREFER over sequential single-pack lookups when comparing entities, with example queries. Does not provide explicit when-not-to-use or alternatives beyond sequential, but the guidance is strong.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description reveals non-invented answers with explicit gaps[], pre-verified facts, parallel execution, 15-60s wait time, and citation format (pipeworx://). This provides rich behavioral context the annotations alone do not.

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

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

The description is well-structured with front-loaded purpose and one sentence per major aspect. Slightly verbose with parallel phrases, but each sentence adds essential information. Appropriate length for 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?

Given no output schema, the description fully compensates by detailing return format (structured findings packet with evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[]). It covers prerequisites, limitations, and expected behavior comprehensively.

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 value by explaining depth enum values (quick=3, standard=5, thorough=8) and that question can be broad/multi-part, which enhances usability 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 performs grounded multi-source research by decomposing questions, routing to 3,745 tools across 884 sources in parallel, and extracting verified evidence per facet. This distinguishes it from sibling tools like ask_pipeworx for single lookups.

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

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

Explicitly advises using for broad/multi-part questions and contrasts with ask_pipeworx for single lookups. Also specifies account requirements (sign in via GitHub) and that depth:'thorough' requires a paid plan, preventing misselection.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by stating it returns schemas with examples and that results are ready to call directly. Consistent with annotations, 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?

Four sentences, front-loaded with main purpose, every sentence adds value. No unnecessary words. Efficiently conveys domain list, return content, and usage advice.

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 explains what is returned (top-N tools with schemas, examples, ready to call). Slightly lacking in detail about exact return format, but adequate for a discovery tool with good 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. Description adds clarity by explaining aliases (q, task, description, search) and providing examples. Summarizes the query purpose effectively.

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

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

Description uses specific verb 'Find tools' and resource 'tools', clearly distinguishes from sibling tools (which are specific tools, not discovery). Lists many domains and states it returns top-N relevant tools with schemas.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools'. Does not provide explicit when-not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint as true/true/true/false. The description adds detail: fans out across multiple sources, returns specific fields, notes patents soft-fail after May 2025, and uses GDELT→GNews fallback. No contradictions; extra 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 front-loaded with example queries and a key directive. It provides all necessary details without redundancy. Slightly long but well-structured, earning its length.

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

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

No output schema is provided, but the description lists the returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents with limitation, news, LEI). This covers the key aspects for a profile tool, leaving the user informed about what to expect.

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 both parameters are documented in the schema. The description adds meaningful context: type only supports 'company' (person/place coming soon), value accepts ticker or zero-padded CIK but not names. This adds nuance beyond the schema's 'description' fields.

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 concrete example queries, states it provides a 'full cross-source profile of a US public company in ONE parallel call,' and distinguishes itself from chaining single-pack lookups. The verb 'profile' and resource 'US public company' are specific and clear.

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 'ALWAYS PREFER over chaining' when a holistic view is asked, and mentions that names are not supported (use resolve_entity first). This provides clear when-to-use and when-not-to-use guidance with 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 already declare destructiveHint=true and idempotentHint=true. Description adds 'previously stored memory' implying existence check, and 'clear sensitive data' adds context. No contradiction. Sufficient disclosure.

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

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

Two sentences: first states purpose, second gives usage guidance. No filler. Front-loaded and efficient.

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

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

For a simple one-parameter tool with no output schema, description covers purpose, usage, and parameter. Does not mention return value or error behavior, but completeness is high given simplicity.

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

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

Schema coverage is 100% with parameter 'key' described as 'Memory key to delete'. Description does not add meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

Description states 'Delete a previously stored memory by key.' Verb 'delete' and resource 'memory' are specific. Distinguishes from siblings 'remember' and 'recall' by contrasting delete vs store/retrieve.

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 provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with 'remember' and 'recall'. No explicit when-not to use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This aligns with the annotations (read-only, idempotent) and provides additional detail on the process. 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 very concise: two sentences that front-load the core action and output, followed by use cases. Every sentence adds value 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 only 2 parameters with full schema coverage and no output schema needed (output is a text blob), the description is complete. It explains what the tool does, how it works, and when to use it. No gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions both parameters (url and max_links) but does not add significant meaning beyond what the schema already provides. The schema descriptions are clear and sufficient.

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

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

The description clearly states the tool generates an llms.txt file, specifying the action 'generate', the resource 'llms.txt file for any URL', and the output format 'standard llms.txt markdown format'. It also lists specific use cases (client site indexing, own project, competitor audit) which distinguishes it from sibling tools that deal with AI visibility, research, etc.

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 'Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This provides clear context for when to use the tool. However, it does not explicitly mention when not to use it or alternatives among siblings, which would elevate the score to 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, idempotentHint, no destructiveness. Description adds what return data includes (fields like description, makers, topics, counts). No negative behaviors disclosed beyond annotations; could mention rate limits or auth but optional API key is already in schema.

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. Every sentence is informative, no fluff. Front-loaded with key action and result.

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 lists returned data sufficiently. Parameters fully covered. Context signals fit a simple read tool. No gaps.

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

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

Schema coverage is 100%, so parameters are documented. Description adds context for slug (example 'notion', where to find it) but does not elaborate on _apiKey beyond schema. Meets baseline with marginal added value.

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 gets full details for a single Product Hunt launch by its slug, listing specific data fields (description, makers, topics, vote/comment counts). This distinguishes it from sibling 'top_launches' 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?

Explicitly says 'Use after top_launches to dig into a specific new product / startup launch,' providing clear when-to-use context and referencing a sibling tool. Also includes an example call.

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 safety (read-only, idempotent, non-destructive). Description adds return field list, providing output context beyond annotations. 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, no fluff, properly front-loaded with verb 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?

For this simple tool with one optional parameter and no output schema, the description fully covers purpose, return data, and usage guidance.

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 one parameter with description. Description clarifies default behavior (active only) by contrasting with include_inactive, adding 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?

Clearly states it lists the caller's active subscriptions and enumerates return fields. Distinguished from siblings like subscribe and unsubscribe by being a listing 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 guidance: use to review before adding more subscriptions or to find an id for cancellation. Implies when not to use (for subscribing or unsubscribing directly).

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

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

Discloses that feedback is read daily by the team, affects roadmap, is rate-limited to 5 per identifier per day, and free (no quota impact). Annotations show 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?

Single well-structured paragraph front-loads purpose, then guidelines, then constraints. Every sentence adds value with no waste.

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

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

Fully describes purpose, when to use, how to format feedback, constraints, and what happens to the feedback. No output schema needed for a send-only 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%; description adds practical guidance: message should be specific (1-2 sentences, 2000 char max), context optional, and explains each type beyond enum labels.

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

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

Description clearly states the tool sends feedback to Pipeworx team for bugs, features, data gaps, or praise. It distinguishes from all siblings, which are query, subscription, or discovery 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?

Explicitly lists when to use: for wrong/stale data (bug), missing tool (feature/data_gap), or praise. Also provides a clear rule to describe issues in terms of Pipeworx tools/packs and not to paste user prompts.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds valuable behavioral context: data is derived from analytics, no PII, and cached for 5min-1h. No contradictions.

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

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

Two paragraphs with clear first sentence and bullet-like use cases. Efficient but slightly verbose with the numbered list; could be tightened without losing meaning.

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?

Covers purpose, use cases, data source, caching, and absence of PII. Output format is only vaguely described ('top tools, top packs, total call volume'), but with no output schema, this is acceptable for a simple trending 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%, so baseline is 3. The description mentions the '24h' default and explains shorter vs longer windows, but this info is already in the schema's parameter description. Thus the description adds no new semantic value beyond what the 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?

The description clearly states it returns trending tools, packs, and call volume over a recent window. It uses specific verbs ('returns') and resources ('top tools, top packs, total call volume'), making the tool's purpose immediately understandable and distinguishable from siblings.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tool, aligning with agent needs). While it doesn't directly contrast with alternatives like 'discover_tools' or 'search_within', the use cases are clear and actionable.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral details: it walks child markets, checks monotonicity, computes partition sums, filters by similarity and partitions, and performs a fill check against live CLOB depth. It explains that realizable edge ≤ 0 means the edge is not executable. There is no contradiction with annotations.

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

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

The description is lengthy (over 250 words) and contains many details. While well-organized with section headers like 'SEMANTIC ANCHOR' and 'FILL CHECK', it could be more concise. Some information could be pruned without losing clarity, but it is still structured and front-loaded with the essential usage requirement.

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

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

Despite lacking an output schema, the description explains the response structure (opportunities array and partition_check object) and covers error conditions (no args, low similarity, placeholder filtering). It also references a sibling tool for custom sizing (polymarket_fill_risk), providing a complete picture for an agent to decide on usage.

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

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

Both parameters (event and topic) have complete schema descriptions. The tool's description greatly enriches them: it explains what each mode does, gives example slugs and seed questions, and notes that full URLs are accepted for event. It also clarifies the exclusive-or requirement. This adds substantial 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 purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic), provides specific verb (find), and resource (arbitrage opportunities on Polymarket). This differentiates it from sibling tools like polymarket_fill_risk or 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?

The description explicitly recommends when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It warns that calling with no arguments fails. It also provides a fill check and advises not to trade when realizable edge is zero. However, it does not explicitly list when not to use this tool versus other arbitrage or risk tools, but the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description goes well beyond by detailing internal models (e.g., lognormal barrier, GDELT ratio), the response structure (by_segment, _diagnostics), caching at KV level, and the Fed bet exclusion. No contradiction with annotations.

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

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

The description is lengthy but well-structured with bolded section headers and clear paragraph breaks. Front-loaded with the core use case. Every sentence contributes meaning, though it could be slightly trimmed for simpler agents. Still, it is organized and readable.

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

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

Given the tool's complexity (9 parameters, 3 model families, no output schema), the description is remarkably complete. It explains the response top-level fields (by_segment, fed_candidates, _diagnostics), the contents of each opportunity (edge_pp_net, kelly_fraction, etc.), and the effects of all knobs. Even caching and diagnostics are 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 coverage is 100% with descriptive parameter descriptions. The main description adds extra context (e.g., slippage_pp comments about zero fees and thin depth, min_partition_leg_kelly detailed explanation) and groups them as 'Tradeable-edge knobs.' This adds semantic value beyond the schema, earning a score above baseline.

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

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

The description clearly states the verb ('Scan'), the resource ('top Polymarket markets'), and the specific purpose ('return opportunities where Pipeworx data disagrees with market price'). It also provides a user-facing tagline ('what should I bet on today') and covers all three model families. This distinguishes it from sibling tools like polymarket_arbitrage by focusing on pipeworx disagreement.

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

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

The description includes explicit usage context ('Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets') and explains the tradeable-edge knobs (min_liquidity, max_spread_pp, etc.). However, it does not explicitly contrast with sibling tools or mention when NOT to use it, so it lacks exclusion guidance.

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

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

The description adds significant behavioral context beyond annotations: snapshot creation triggers (cache-miss), history depth (60-day TTL), decay computation basis (daily closes, not intraday), and gap meaning. This complements the readOnlyHint and idempotentHint annotations effectively.

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 but well-structured and front-loaded with the core purpose. Every sentence adds value, though some details (e.g., JSON-like output structure) could be slightly more concise. Still highly efficient 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 explains the return structure (tracked[], expired[], snapshot_dates[]) and key metrics (trend, decay_pp_per_day, lifespan). It also covers limitations (history depth, decay basis). Very complete given the tool's complexity.

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

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

The input schema already covers both parameters with descriptions, but the description adds default values (14, '1wk'), clamp range (2-30), and clarifies 'window' as 'snapshot family'. This provides valuable additional context beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, with a specific verb+resource combination. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis and decay trends.

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 context about when this tool is valuable (differentiating between fresh and old edges) and explains the output structure. However, it does not explicitly name alternatives or when not to use it, though the purpose is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds rich behavioral context: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; for basket: theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, forced_directional_risk). No contradictions.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence adds value, and the most important information (purpose and when to use) is front-loaded. Despite length, it is efficient and scannable.

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

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

Given the complexity of the tool (two modes, multiple return fields, and no output schema), the description thoroughly explains all return values, usage context, and risk warnings. It covers why each field matters (e.g., 'thin_legs[]' and 'forced_directional_risk' for hedge risks). 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 description coverage is 100%, but the description adds significant meaning beyond the schema. It explains the dual role of 'side' (single-market vs basket, with auto-detection in basket), the interpretation of 'size_usd' in basket mode ('settlement notional S – shares per leg'), and the default values and constraints. This provides an agent with concrete context for parameter usage.

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

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

The description uses specific verbs ('check', 'walks') and resources ('CLOB order-book depth', 'market slug', 'event slug') to clearly state what the tool does. It distinguishes two distinct modes (single-market and basket) and explains their outputs, differentiating it from sibling tools like polymarket_arbitrage and 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?

Explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also advises against skipping it by explaining the risks of partial fills and unhedged positions.

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), description details response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains when spreads are invalid. 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?

Front-loaded with purpose, then logically organized into modes, response, and safety fields. Every sentence provides value; no fluff despite comprehensive coverage.

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 fully explains response fields (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and how to interpret them. Complete for a complex cross-venue spread 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 descriptions already cover all 3 parameters; description adds context (topic as macro shortcut, ticker/slug overrides) and examples (fed, btc) that enhance 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?

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes two modes (topic shortcuts vs explicit pairings), which differentiates it from sibling tools like polymarket_arbitrage.

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

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

Explicitly describes when to use each mode and warns that most pre-mapped topics currently return compatibility warnings, guiding the agent not to expect tradeable spreads lightly.

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

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

Adds scoping detail (anonymous IP, key hash, account ID) beyond annotations. Annotations already declare readOnly, idempotent, non-destructive. No contradiction. Explains relationship to remember/forget.

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 efficient sentences covering action, use case, and scoping. No wasted words. Front-loaded with core action.

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

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

Complete for a simple retrieval tool. Explains both modes, return behavior (value or list), scoping, and pairing. No output schema but description suffices.

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 full description of 'key' parameter. Description repeats 'omit to list all keys', adding no new meaning beyond schema. Baseline 3 is appropriate.

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

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

Clearly states the tool retrieves a saved value or lists all keys, with specific verb-resource pairing. Distinguishes the two modes (with/without key). Fully clarifies purpose.

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

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

Tells when to use (look up stored context) and mentions pairing with remember and forget. Implicitly avoids re-deriving info. Does not explicitly exclude alternatives, but sibling tools (remember, forget) help differentiate.

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 state readOnly, openWorld, idempotent, non-destructive. Description adds: returns recent alerts from persisted feed, each with source, citation_uri, raw payload; mark_read flags events read; polls work fine. 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 concise sentences: purpose, return details, usage guidance. Front-loaded, no wasted 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 no output schema, description covers return fields (source, citation_uri, payload). Explains filtering, mark_read, and alternative access. Lacks pagination specifics but limit parameter covers max results. Adequate for a read-only 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 100% (baseline 3). Description adds examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains mark_read behavior. Does not explain limit or unread_only beyond schema, but still adds value.

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+resource: 'Pull fired events from your subscription feed.' Identifies the resource and action. Could be more explicit in differentiating from siblings like list_subscriptions, but purpose is unambiguous.

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

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

Provides filter options (type, since) and mark_read flag with effect on subsequent calls. Also notes alternative access via URL. Lacks explicit 'when not to use' but gives good 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=true, idempotentHint=true, destructiveHint=false. The description adds significant context: parallel fan-out, GDELT preferred with GNews fallback on rate limit/5xx, USPTO soft-fails until reactivated, and return structure with citation URIs.

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 somewhat lengthy but front-loaded with example queries. Every sentence adds value, though could be slightly tighter. Still highly effective.

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

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

Given the complexity (multiple sources, fallback, soft-fail) and no output schema, the description fully explains behavior, sources, return structure (grouped changes + count + URIs), and parameter usage. Complete coverage.

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

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

Schema coverage is 100% but description adds meaning: 'type' only supports company, 'since' accepts ISO date or relative shorthand with suggested values, 'value' examples as ticker or CIK. Goes beyond schema rephrasing.

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 provides clear example queries and states it returns a change feed for a company in a time window, fanning out to SEC EDGAR, GDELT→GNews, and USPTO. It explicitly distinguishes from sibling tool entity_profile.

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

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

The description explicitly states when to use this tool (recent changes) and when to use entity_profile instead (static profile). It also gives example input phrases and suggested defaults for 'since'.

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 provides critical behavioral details beyond annotations: persistence differences for authenticated vs. anonymous users (cross-session vs. 24-hour TTL), scoping by identifier, and pairing with recall/forget. Annotations (e.g., idempotentHint=true) are consistent, and no contradiction is present.

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 extremely concise, with the first sentence stating purpose, followed by usage guidance and then persistence details. Every sentence contributes essential information, and the structure is logically ordered. No filler or redundancy.

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

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

Given the tool’s simplicity (two required string params, no output schema, annotations present), the description is fully adequate. It covers purpose, usage, persistence, pairing, and scope. No gaps are evident for an AI agent to correctly invoke the tool.

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

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

The input schema already provides 100% coverage for both parameters (key and value) with descriptions. The tool description adds value by reiterating the key-value nature and giving examples in the schema (e.g., key patterns). However, it doesn't significantly expand 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 purpose: saving data for reuse. It uses specific verbs ('Save'), identifies the resource (key-value pairs), and distinguishes from siblings by mentioning 'recall' and 'forget' explicitly. The scope (cross-session) is also clarified.

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 advises when to use the tool ('when you discover something worth carrying forward') and implicitly when not (if data is not worth persisting). It also denotes paired tools (recall, forget), providing context. However, it lacks explicit exclusions or alternative tool scenarios beyond those directly related.

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. The description adds valuable behavioral context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' It also mentions auto-disambiguation for company inputs. This goes beyond the annotations and provides practical insight into the tool's operation.

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

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

The description is well-structured with examples first, then function, then supported types. However, it is slightly verbose, repeating 'accepts ticker, CIK, or company name as input' which is already implied in the type description. Each sentence is valuable, but minor redundancy reduces conciseness.

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

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

Given no output schema, the description fully explains return values for both entity types, including citation URIs. It covers internal cascading, auto-disambiguation, and usage hint ('Use FIRST'). This is comprehensive for a lookup tool, leaving no ambiguity about what results to expect.

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%, but the description adds significant meaning beyond the schema. For the 'value' parameter, it explains acceptable formats per type (e.g., ticker, CIK, name for company; brand or generic for drug) and details the return structure (e.g., ticker + 10-digit CIK + company_name + citation URI). This helps the agent understand both input and output semantics.

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 purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides concrete examples like ticker, CIK, RxCUI, and explicitly lists supported entity types with their return structures. This differentiates it well from sibling tools that may use IDs or provide different entity information.

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 'Use FIRST whenever you have a name but need an ID,' which is strong when-to-use guidance. However, it does not explicitly mention when not to use it or compare directly with sibling tools like entity_profile or compare_entities, so some usage boundaries are implied rather than stated.

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 false, so the safety profile is clear. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, signal density. No contradictions with annotations.

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

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

Three sentences with no extraneous content. The first immediately states what the tool does, the second adds detail, the third provides a concrete example. Efficient 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?

No output schema exists, so the description must explain return values. It does so clearly: 'ranked list with score, confidence, signal density per entity.' Combined with good annotations and schema coverage, the description completes the context despite lacking an output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the role of the first entity in the 'entities' array, the default model ('workers-ai' is free), when _apiKey is required, and how the 'context' parameter disambiguates common names. This goes 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?

The description specifies a clear verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison) by naming the specific action and underlying mechanism.

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 a concrete use case ('competitive AI-marketing audits') and an example question. It notes that the first entity is the subject and the rest are competitors, aiding correct invocation. However, it does not explicitly state when not to use or mention alternatives.

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

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

Adds significant behavioral context beyond annotations, such as partial failures degrading gracefully and bundlephobia's first measurement taking 5-30 seconds. 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 that front-loads the purpose. Every sentence adds value: purpose, sources, usage, scope, return format, and failure behavior. No wasted 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?

Despite no output schema, description lists return fields in detail (summary block, advisories, links, alternative versions). Also covers behavior (graceful degradation) and timing. Complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal extra meaning (e.g., scoped packages accepted) but mostly restates 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: a composite check for adding an npm package, fanning out across multiple sources. It distinguishes itself from sibling tools by being npm-specific and aggregating multiple checks into one call.

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 usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also clarifies scope: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds behavioral details: embedding model (BGE-base-en), chunking (500-char overlapping windows), character cap (200K 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?

The description is dense but well-structured with clear sentences. Every sentence adds value, though slightly verbose. Minor improvements could tighten phrasing 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?

Despite lacking an output schema, the description explains return format (passages, offsets, similarity scores) and pairs with sibling tool ask_pipeworx_grounded. Complete for a search tool with given complexity.

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

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

Schema descriptions cover 100% of parameters, but the description adds value with examples for query ('supply-chain risk'), default limit, and a note on max text length. This enriches the schema-defined semantics.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying the inputs (text, query) and outputs (passages with offsets and similarity scores). It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining the use case.

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

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

Explicitly says when to use (record too big for prompt) and when not to (use ask_pipeworx_grounded for whole document grounding). Provides clear context and 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?

Discloses behavioral traits beyond annotations: delivery channel limitations (SMS cap), webhook signing, auto-disable after failures, and phone verification. Annotations provide some info, but description adds significant operational details.

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

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

Well-structured with bulleting for types and delivery channels. Slightly long but each sentence adds value. Front-loaded with main 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?

Covers key aspects: return value (subscription id), delivery channels, prerequisites. Lacks detail on error handling or duplicate subscription behavior, but generally complete for an alert subscription 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?

Adds substantial meaning beyond the input schema: provides concrete examples for each subscription type, details delivery options with real-world constraints (phone verification, webhook signing). Schema coverage is 100%, but description enriches it greatly.

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. Distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Provides context on when to use (for persistent alerts) and prerequisites (OAuth account, phone verification for SMS). Does not explicitly state when not to use, but the description sets clear usage 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 cover readOnly, idempotent, openWorld, non-destructive. Description adds that it returns live example questions with tool+argument shapes, drawn from a catalog of thousands of tools. 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 relatively long but front-loaded with triggers and structured. Every sentence adds value, though could be slightly tighter 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?

For a simple tool with no output schema, the description fully explains behavior, use cases, parameters, and output. No missing critical information.

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 a single optional topic parameter. Description adds the list of valid topics (finance, pharma, etc.) and explains that omitting gives a cross-category spread, significantly enhancing 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 tool is an onboarding entry point for an agent to discover what questions to ask Pipeworx. It specifies that it returns category-bucketed example questions and distinguishes itself from siblings like ask_pipeworx.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides alternatives (with/without topic) and context for when 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 declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by specifying output fields (name, tagline, votes, comments, URLs, topics) and the example, which helps set expectations 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 two sentences plus an example, front-loaded with the action verb 'Get'. Every sentence adds information; no wasted 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?

No output schema exists, but the description lists all returned fields. It also notes limits (max 20) and provides an example. For a simple list tool, this is sufficiently complete, though pagination or filtering details are omitted.

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

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

Schema coverage is 100%, so the description does not add new meaning beyond the schema. The example shows usage but the parameters are already fully documented in the input 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 specifically states the tool retrieves today's and recent top Product Hunt launches, listing returned fields. It clearly distinguishes from siblings which are unrelated (e.g., polymarket tools, entity 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 explains when to use (see today's/recent launches or trending products) and provides an example. It does not explicitly mention when not to use or alternatives, but the context is clear.

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

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

Beyond annotations (idempotentHint true, destructiveHint false), the description adds valuable context: ownership enforcement, deactivation vs deletion, and historical event availability via 'recent_alerts'. No contradictions with annotations.

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

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

Three concise sentences with front-loaded main action. Every sentence adds value 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 a single parameter and no output schema, the description fully covers behavioral effects, ownership constraints, side effects, and links to related tools. No gaps.

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

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

Schema coverage is 100%, and the schema already describes 'id' as 'Subscription id (uuid) returned by subscribe'. The description does not add extra semantic detail, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', using a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 ownership enforcement ('you can only cancel your own subscriptions') and explains the behavioral outcome (deactivated not deleted) with a link to 'recent_alerts'. This provides clear context for when to use 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: returns a verdict with structured output, actual value with citation, and percent delta. It also discloses the underlying process (parsing, entity resolution, data lookup, numeric comparison) without contradicting 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 yet packed with essential information. It opens with recognizable query patterns, states the use case, defines the scope, and lists output details. Every sentence earns its place without redundancy.

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

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

Given the tool's simplicity (one required parameter, no output schema, rich annotations), the description provides complete context. It explains what kinds of claims work, what the output includes, and why this tool is preferable to alternatives, enabling an agent to decide confidently.

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 a description for the single parameter 'claim'. The tool description enhances this by providing examples of valid claims (e.g., 'Apple's FY2024 revenue was $400 billion') and specifying the supported claim types, adding meaning beyond the schema alone.

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

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

The description clearly states the tool is for natural-language claim verification with specific examples ("Is it true that…", "fact check"). It specifies the supported domain (company-financial claims) and data sources (SEC EDGAR + XBRL), distinguishing it from siblings like ai_visibility_check or ask_pipeworx.

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

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

Explicit guidance is provided: 'Use whenever the agent needs to check whether something a user said is factually correct.' The description also notes scope limitations (v1 supports company-financial claims), helping agents know when not to use it. It does not explicitly contrast with siblings but implies uniqueness by stating it replaces multiple sequential calls.

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