Predictit

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) align with description. Description adds important behavioral details: requires Anthropic API key for that model, costs are passed through, returns per-model metrics. 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 purpose, no superfluous words. Efficiently communicates all necessary 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?

No output schema, but description explains return structure (per-model score, confidence, signals, raw_response + combined view). Mentions useful for audits/checks. Could note limits or pagination, but not required given tool 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?

Parameter descriptions in schema are already good (100% coverage). Description adds value by explaining defaults (workers-ai), purpose of _apiKey (BYO key for Anthropic, passthrough), and context disambiguation. Adds meaningful 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 probes LLMs for knowledge about an entity and scores visibility per model (0-100). It specifies default model and optional Anthropic probe. Distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on scoring across models.

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 cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. While it doesn't explicitly say when not to use, the context is clear and the description implies this tool is for visibility scoring, not deep research.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it routes to 3,777 tools across 896 sources, returns structured answers with pipeworx:// citation URIs. This goes beyond annotations. Minor omission: no mention of latency or error behavior.

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

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

Description is well-structured: starts with the key preference advice, then explains mechanism, then usage guidelines, then examples. It is not overly verbose but could be slightly trimmed. However, every sentence adds value. A minor deduction for including 'PREFER OVER WEB SEARCH' which is already a strong usage guideline.

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 covers the return format (structured answer with citation URIs). The parameter is a simple string, and the description gives ample guidance on how to phrase questions. The tool is a query tool, and the description leaves no obvious gaps for an AI agent to misuse.

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

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

Schema description coverage is 100%: all 6 parameters (question and aliases) are described. The description does not add details about parameter constraints or format beyond what the schema provides. Baseline score of 3 is appropriate since schema handles parameter semantics adequately.

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

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

Description clearly states it is for querying structured data from verified sources with citations. It distinguishes itself from web search by explicitly saying 'PREFER OVER WEB SEARCH'. The verb 'ask' combined with 'routes the question to the right one of 3,777 tools' makes purpose very specific.

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: for factual questions about real-world entities, events, numbers. It lists example query patterns like 'what is', 'look up', 'find', etc. and provides concrete examples. It also implies when not to use (non-factual or subjective queries) by contrasting with web search.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, etc. The description adds context beyond annotations by detailing the grounded extraction process, evidence return, and explicit refusal reasons. It confirms the tool is a read-only, idempotent operation with no destructive side effects.

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

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

The description is well-structured and front-loaded with the main purpose. It is somewhat lengthy but packs essential information without redundancy. 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 the complexity of the tool (grounded answers, refusal reasons, evidence), the description thoroughly explains return structure, error reasons, and trade-offs versus the sibling. It provides a complete picture for an agent to use the 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% with all 6 parameters described in the schema. The description does not add significant additional meaning beyond schema, which already defines the question parameter and aliases. 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and explains that it uses tool results to extract answers with evidence. It distinguishes from sibling 'ask_pipeworx' by noting it costs an extra LLM call and is for critical use cases.

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 ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), providing clear decision 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 extensively documents behavioral traits beyond annotations: safety features (low-confidence short-circuit, closed market status), wide-spread market warnings, resolution-rule risk, parent_event extractor, news fallback fields, and more. No contradictions with annotations.

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

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

The description is very long and dense, covering many technical details. While every sentence adds value, it is not concise and could benefit from better structuring or trimming. It front-loads the purpose but then goes into extensive specifics, which may overwhelm.

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

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

Given the complexity of the tool (multiple classifiers, fan-outs, response shapes, error handling) and no output schema, the description is exceptionally complete. It covers inputs, behavior, response fields, safety, edge cases, resolution-rule risk, and fallbacks, leaving little ambiguity for an AI 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%, so baseline is 3. The description adds value by explaining input types (slug, URL, question text), default behavior for depth ('Default thorough'), and when to use include_raw (size implications). This context helps the agent choose appropriate parameter values.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and action (pull Pipeworx data). This distinguishes it from sibling tools like get_market or search_markets, which are simpler or more focused.

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

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

Provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of classifiers and fan-outs, but does not explicitly state when not to use this tool versus siblings. However, the use cases are clear enough to guide the agent.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: parallel execution, handling of off-calendar fiscal years, sorted results, and citation URIs. No contradiction with annotations.

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

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

The description is concise yet packed with information. It starts with example queries, defines the purpose, details entity-specific data, and mentions result format. Every sentence adds value, and there is 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 no output schema, the description adequately covers return format (paired data with citation URIs) and sorting behavior. The tool has moderate complexity with two parameters, and the description sufficiently completes the 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 has 100% coverage with descriptions for both parameters. The description adds extra meaning by explaining what each entity type pulls (financials from SEC EDGAR/XBRL, adverse event counts) and providing examples, going beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, with specific examples of what each entity type retrieves. It distinguishes itself from sequential lookups, making the 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use. It does not explicitly mention when not to use, 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?

Beyond annotations (readOnly, idempotent, etc.), the description reveals key behaviors: decomposes questions, routes in parallel, returns verbatim evidence, gaps for unanswerable facets, never invents, and expects 15-60s. 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 is dense but every sentence adds value. Front-loaded with purpose and key details. Could be slightly more structured, but 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?

No output schema, so description fully compensates by describing the return packet (evidence, gaps, citations). Covers all important aspects: purpose, usage, prerequisites, limitations, behavior.

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

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

Schema coverage is 100% so baseline is 3. Description adds meaning: explains depth values as facet counts and that question can be broad/multi-part. Provides 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 it does 'grounded multi-source research in ONE call', detailing decomposition into sub-questions and parallel routing. It distinguishes itself from siblings like ask_pipeworx, which is 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 says 'Use for broad or multi-part questions' and 'use ask_pipeworx for single lookups'. Also mentions account prerequisites and depth restrictions (thorough requires paid plan).

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 (readOnly, idempotent, non-destructive); description adds useful context like returning ready-to-call tools with schemas, 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?

Single, well-structured paragraph with front-loaded purpose, examples, return value, and usage advice; 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?

Comprehensive for a discovery tool: explains purpose, usage, return schema availability, and first-call strategy; no output schema needed given description clarity.

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?

Full schema coverage (baseline 3). Description enriches with query examples (e.g., 'analyze housing market trends') and mentions aliases, aiding usage 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 'Find tools by describing the data or task' with specific verb and resource, and distinguishes from sibling tools that perform other actions.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use and implied when-not.

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, openWorldHint, idempotentHint, destructiveHint), the description details the parallel fan-out across multiple sources, the specific return fields (cik, filings with URIs, fundamentals sorted, patents with soft-fail, news fallback, LEI), and the patent API sunset behavior. Adds rich context without contradiction.

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

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

The description is relatively long but every sentence provides useful information. It is front-loaded with the core purpose and usage guidance. Could be slightly more structured (e.g., bullet points), but it remains concise for the amount of detail it conveys.

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 what the tool returns: cik, company_name, recent_filings with URIs, fundamentals (with specific fields and sorting), patents (with sunset caveat), news fallback, and LEI. It also covers the parallel call behavior and soft-fail, making it complete for 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 already provides descriptions for both parameters (type enum with 'company', value as ticker or CIK). Description reinforces that names are not supported and adds context about the value format, improving clarity 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?

Explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and differentiates from chaining single-pack lookups when a holistic view is needed. Clearly distinguishes from siblings like deep_research and compare_entities by specifying 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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also notes names not supported and advises to use resolve_entity first, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds valuable context about clearing sensitive data, reinforcing the destructive nature without contradiction.

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

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

Two concise sentences that front-load the action and follow with usage context. No wasted words; 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 the tool's simplicity (one parameter, no output schema), the description fully covers purpose, usage conditions, and relationship to sibling tools. It is complete and self-contained.

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

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

Schema coverage is 100%, and the description adds no extra meaning beyond the schema's 'Memory key to delete'. This meets the baseline for full schema coverage.

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

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

The description uses a specific verb 'delete' and clearly identifies the resource 'memory by key'. It also references sibling tools 'remember' and 'recall', distinguishing its role in the memory management workflow.

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 context is stale, the task is done, or you want to clear sensitive data'. It also advises pairing with 'remember' and 'recall', providing clear alternatives.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral context: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. This goes beyond annotations by explaining the process and output format.

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

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

The description is two focused sentences plus a bullet list of use cases. It starts with the main action and is front-loaded. Every sentence adds value, though it could be slightly more compressed.

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

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

For a tool with 2 simple parameters, rich annotations, and no output schema, the description is sufficiently complete. It explains the output format ('single text blob ready to drop at site-root/llms.txt') and the process. No critical gaps for its intended 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 description coverage is 100%, so the input schema already documents both parameters. The tool description does not add extra parameter semantics; it only hints at the URL's role through 'Fetches the page'. 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 action ('generate a production-ready llms.txt file'), the resource (any URL), and the outcome (extracts title/description/key links, emits standard format). It also lists specific use cases, distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on llms.txt generation.

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 lists three use cases: getting a client's site indexed, drafting for own project, or auditing competitor. This provides clear context on when to use the tool, though it does not mention when not to use or alternative tools.

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

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

Adds value beyond annotations by noting keyless access ('Keyless'), explaining contract prices as implied probabilities (0–100%), and providing an example ID. 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, each serving a distinct purpose: main function, price context, and sibling guidance. No redundant or wasteful 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?

Fully covers relevant context for a simple tool with one required parameter and no output schema: purpose, parameter usage, and how to find IDs.

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

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

With 100% schema coverage, the schema already documents the id parameter. The description reinforces with an example but adds limited new semantic meaning beyond that 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?

Clearly states 'Get one PredictIt market by id with ALL of its contracts', specifying verb, resource, and scope. Distinguishes from sibling tools list_markets and search_markets for finding IDs.

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 guides to use list_markets or search_markets to find IDs if not known. Does not cover when to avoid this tool but provides clear context for basic 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 indicate read-only, idempotent, non-destructive. The description adds valuable behavioral traits: keyless access, compact output with up to 8 contracts, and implied probability interpretation. 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: first concise purpose and scope, second additional details. No filler, 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?

Given no output schema, the description compensates by describing return format (compact markets, up to 8 contracts). Covers domain, authentication, and pricing semantics thoroughly for a simple list tool.

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

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

Schema covers 100% of parameters with descriptions. The description does not add new parameter meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as listing active PredictIt prediction markets with specific domain context (US-politics, elections). It distinguishes from siblings like get_market and search_markets by specifying 'List' vs. singular retrieval or search.

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

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

The description implies usage for browsing overall market set, mentions 'Keyless' (no auth needed), and explains output format. However, it doesn't explicitly compare to sibling search_markets or provide when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds details on return fields and the include_inactive parameter effect, 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?

Two sentences: first states purpose and return fields, second gives usage guidance. No wasted words, front-loaded with core 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 list tool with one optional parameter, the description provides return fields and usage context. Combined with full annotations, it is complete.

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

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

Schema coverage is 100% with a clear description for the single parameter 'include_inactive'. Description adds context by mentioning 'active subscriptions' but doesn't add substantial new 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?

Description clearly states the verb 'List' and the resource 'subscriptions', specifying scope 'caller's active'. Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly mention when not to use alternatives, 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 indicate readOnlyHint=false, destructiveHint=false, etc. The description adds: rate-limited to 5 per identifier per day, free (doesn't count against quota), team reads daily. 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 concise and well-structured. It front-loads the purpose, then provides usage guidelines, behavioral notes, and constraints. 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 the tool's simplicity (3 params, no output schema), the description covers purpose, usage, rate limits, quota, and constraints. 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% with descriptions. The description adds significant meaning: explains enum values for 'type', instructs to be specific in 'message', and clarifies that 'context' is optional structured context. This goes beyond the schema.

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

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

The description clearly states the tool is for sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes itself from siblings by specifying the feedback use cases and provides examples of when to use it.

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: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives negative guidance: 'Don't paste the end-user's prompt.'

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. The description adds value beyond annotations by stating it is self-aggregating, derived from CF analytics-engine, no PII, and cached 5min-1h depending on window.

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?

Concise, front-loaded with main purpose, uses bullet points for use cases, no wasted words. 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?

The tool is simple with one parameter, and the description adequately explains the output (top tools, packs, call volume). However, without an output schema, explicitly listing the result format (e.g., list of objects with fields) would improve completeness.

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 enum and description. The description adds additional semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enhancing agent understanding of parameter choice.

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 (returns) and resource (trending data: top tools, packs, call volume) and distinguishes its purpose from sibling tools like ask_pipeworx or discover_tools by specifying 'What other AI agents are calling on Pipeworx right now.'

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

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

Provides explicit use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. Clear context but lacks explicit when-not-to-use or alternative tool mentions.

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?

Extensive behavioral disclosure covering monotonicity checks, partition verification, fill checks, semantic anchors, placeholders filtering, and return format. Far exceeds the information provided by annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

Though lengthy, every sentence adds value and the critical usage requirement ('REQUIRES one of event or topic') is front-loaded. No superfluous content 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?

Describes response structure (opportunities[], partition_check, fill_check) and edge cases (missing args, placeholder filters). With no output schema, the description fully covers what the agent can 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?

Adds significant meaning beyond schema: explains what event slugs and topic strings look like, how they are used in single-event vs cross-event mode, and provides examples. Schema coverage is 100% but description enriches 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 finds arbitrage opportunities using monotonicity violations and partition-sum checks, and distinguishes between single-event (event) and cross-event (topic) modes. This specificity differentiates it from sibling tools like polymarket_edges or polymarket_kalshi_spread.

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 that one of event or topic is required, and describes when to use each. Also advises using polymarket_fill_risk for custom sizing, providing clear guidance on alternatives.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, destructiveHint=false, meaning safe reads. The description adds extensive behavioral context: detailed model families (e.g., partition_overround with sport-specific alphas), edge calculation with slippage, Kelly sizing, and empty-segment diagnostics. No contradiction with annotations.

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

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

The description is comprehensive and front-loaded with purpose, but it is long and includes detailed internal logic (e.g., specific alpha values). Given the tool's complexity, every sentence adds value, but a slightly more concise treatment of internal details could improve readability without losing essential information.

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

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

No output schema exists, so the description must explain return values. It does so thoroughly: top-level fields (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and caching behavior. Agents can fully understand 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?

All 9 parameters have schema descriptions (100% coverage). The description adds significant value beyond the schema by explaining parameter behavior in context, such as slippage_pp noting zero trading fees but typical bid/ask costs, and min_partition_leg_kelly explaining why min_kelly doesn't filter partition arbs. This helps agents make informed choices.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly naming its purpose as 'what should I bet on today'. It distinguishes itself from sibling tools by detailing three model families, which is unique among the listed siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides explicit guidance on when to use the tool ('what should I bet on today') and describes configurable knobs (e.g., min_liquidity, max_spread_pp) that help agents avoid non-realizable edges. It also notes that Fed bets appear but are excluded from ranking due to data limitations. However, it does not explicitly state alternatives or when not to use this tool.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds significant context: response structure (tracked, expired, snapshot_dates), interpretation of trends, limits (60-day TTL, daily closes), and explanation of gaps. This exceeds what annotations 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 core question and provides a structured breakdown of the response and limits. It is thoroughly informative without being overly verbose, though slight condensation could improve 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?

Despite lacking an output schema, the description thoroughly explains the response fields and their semantics, including edge decay calculations, expiration, and data gaps. It covers complexity well, though it could note potential error conditions or empty 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?

Both parameters are fully described in the schema (100% coverage). The description adds default values, clamping range for days, and clarifies that window is a 'snapshot family'. This is helpful but not essential beyond the schema.

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

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

The description clearly defines the tool's purpose: analyzing edge persistence and decay over time using daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes the telemetry from single-snapshot tools like polymarket_edges, though it doesn't explicitly name alternatives.

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 tool's usage context is implied by its purpose (e.g., for historical analysis vs. current snapshot), but there is no explicit guidance on when to use this tool versus siblings like polymarket_edges or polymarket_arbitrage. The description omits when-not-to-use scenarios.

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

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

Annotations already declare it read-only, idempotent, and non-destructive. Description adds context about what the tool checks and returns (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) 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?

Long but well-structured with uppercase mode markers and clear sections. Front-loaded with purpose. Every sentence provides value given tool complexity, though could be slightly tightened.

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?

Completely covers the tool's functionality: explains both modes, return fields, edge cases (thin legs, forced directional risk), and when to use. No missing crucial information despite lack of 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 already has 100% description coverage. Description adds extra context like default behavior for side in basket mode, interpretation of size_usd (max spend on buys, target proceeds on sells), and auto-detection of basket/single mode.

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

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

Describes exactly what it does: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' Clearly distinguishes two modes (single-market and basket) and their specific use cases.

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

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

Explicitly states when to use: before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or trades above ~$500. Also warns about thin books and partial basket fills converting arb into unhedged position.

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 annotations by detailing behavioral nuances: compatibility warnings for non-equivalent bet shapes, temporal alignment, skipped leg counters, and the rarity of real spreads. It fully discloses limitations and edge cases.

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 and information-dense, with each sentence adding value. It could be slightly more concise, but the structure with sections (TWO MODES, RESPONSE, SAFETY FIELDS) aids readability.

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

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

Given no output schema, the description comprehensively explains the response format, safety fields, and edge cases like temporal alignment and skipped legs. It covers all necessary context for an AI 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?

With 100% schema coverage, each parameter already has a description. The tool description adds value by explaining the interaction between parameters (modes, override behavior) and providing examples in the schema.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, with two specific modes (topic shortcuts and explicit tickers). It distinguishes itself from siblings by focusing specifically on this pair of venues and includes details on when spreads are meaningful.

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 each mode (pre-mapped topics vs explicit pairings) and warns that pre-mapped topics often yield compatibility warnings, providing honest guidance. It does not explicitly list when not to use it or alternatives among siblings, 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=true, idempotentHint=true, and destructiveHint=false. The description adds transparency about scoping (per identifier) and relationships with remember/forget. This additional context is valuable but could mention storage limits or return format.

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

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

Three sentences with no wasted words. The most important information (action and conditions) is in the first sentence. Structure is front-loaded and logical.

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 retrieval tool with no output schema, the description covers purpose, scope, and pairing. However, it omits any hint about the return format (e.g., string value vs list of strings). This gap moderately impacts utility.

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 the single parameter. The description reinforces that omitting the key lists all saved keys, which the schema also states. Beyond this confirmation, no new parameter meaning is added.

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

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

The description clearly states the tool retrieves previously saved values or lists all keys, explicitly distinguishing it from sibling tools 'remember' and 'forget'. The verbs 'retrieve' and 'list' are specific and unambiguous.

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

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

The description provides clear usage context: retrieving stored context without re-deriving it, and scoping by identifier. It pairs with remember and forget, offering implicit guidance on when not to use. Missing explicit exclusions like 'do not use to store new data'.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds context by explaining the effect of mark_read:true (flags events as read) and the persisted feed nature. It also mentions the polling behavior. 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 moderately concise (4 sentences) with front-loaded action. It efficiently conveys key information without extraneous detail, though it could be slightly tighter.

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

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

Given the absence of an output schema, the description adequately explains what the tool returns (alerts with specific fields) and how to use parameters. It mentions an alternative access method. Minor omission: no mention of pagination or return format for lists, but sufficient for typical usage.

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

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

Schema covers all 5 parameters with descriptions. The description enriches key parameters: gives an example for type ('sec_8k'), specifies ISO format for since, and explains the side effect of mark_read. It does not cover limit or unread_only deeply, but adds 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 'Pull fired events from your subscription feed' and details the returned fields (source, citation_uri, payload). The tool is distinct from sibling tools like list_subscriptions, which manage subscriptions rather than events. It also mentions an alternative REST endpoint, further clarifying its 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?

The description provides usage context: filtering by type and since, setting mark_read for read tracking, and polling suitability. It also notes an alternative REST endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or compare it to all 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals fallback logic between GDELT and GNews, soft-fail for USPTO, and return structure with citation URIs. This fully discloses behavioral traits.

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 structured logically, but it is slightly verbose. Every sentence adds value, but could be tightened.

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 the return structure (changes grouped by source, total_changes count, citation URIs) and covers fallback behaviors, making it complete for a complex multi-source tool.

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

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

Schema coverage is 100%, but the description adds meaningful examples for since (ISO dates or relative shorthand with typical monitoring suggestion), clarifies value accepts ticker or CIK, and notes type is only company. This enhances 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 provides a change feed for a company in a specified window, sourcing from SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes from sibling entity_profile by contrasting dynamic changes vs static 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 gives example queries ("What's new with X") and recommends entity_profile for static profile. It doesn't list exclusions 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?

Adds key behavioral details beyond annotations: scoping by identifier, persistence durations (24h anonymous, persistent authenticated), and key-value storage format. No contradiction with idempotentHint=true or destructiveHint=false.

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 usage, then storage details. Every sentence is informative without redundancy. Length is appropriate for the tool's simplicity.

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 all necessary aspects: purpose, when to use, pairing with siblings, key-value format, persistence, examples. No missing information for an agent to use correctly.

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

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

Schema coverage is 100% with descriptive param docs. Description adds value by giving example key patterns ('subject_property', 'target_ticker') and clarifying value is any text, which aids correct usage.

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

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

The description clearly states the verb 'Save' and resource 'data' for later reuse across conversations and sessions. It distinguishes from sibling tools by explicitly mentioning pairing with recall and forget, and contrasts with anonymous vs authenticated retention.

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: 'discover something worth carrying forward' with examples (ticker, address, preference). Also tells how to pair with recall/forget and notes session duration differences for authenticated vs anonymous users.

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, and openWorldHint=true, reducing the burden. The description adds value by noting that 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups,' hinting at efficiency. It also clarifies output structure (e.g., ticker + CIK for company) 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 front-loaded with examples and clearly structured with sections for supported types. Every sentence adds value, but it could be slightly more concise by removing redundancy (e.g., repeating 'returns' in each type). Overall, it is well-organized and informative.

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 explains return values (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug) and mentions citation URIs. It covers supported types and input variants. While it could specify edge cases (e.g., ambiguous names), it is sufficiently complete for most use cases.

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% (both parameters have descriptions). The description adds examples (AAPL, 0000320193, ozempic) and explains what each type returns, enhancing understanding beyond the schema's enum and string descriptions. This is valuable for the agent to construct correct inputs.

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 examples of user queries, then explicitly states 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It clearly identifies the verb (resolve) and resource (names to identifiers). It distinguishes from siblings by being the go-to tool for entity resolution, while siblings like 'entity_profile' or 'compare_entities' are for post-resolution tasks.

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 FIRST whenever you have a name but need an ID.' It does not explicitly mention when not to use or alternatives, but the context implies that if an ID is already available, other tools may be more appropriate. Among siblings, only 'compare_entities' and 'entity_profile' are tangentially related, but the description doesn't discuss them, leaving 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 already declare readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral details: probes each entity with ai_visibility_check, returns ranked list with score, confidence, signal density per entity. 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, front-loaded with the primary action and outcome. Each sentence serves a purpose: what it does, how it works, and when to use it. No redundancy or fluff.

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

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

Despite no output schema, the description clearly explains return structure (ranked list with score, confidence, signal density). It covers all key aspects: purpose, usage, parameters, and output, making it self-sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, but description adds value beyond schema: explains that the first entry is treated as the 'subject' for narrative, clarifies context usage, and describes how models and apiKey interact. This goes 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 explicitly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks them by score. It clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic).

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: 'Useful for competitive AI-marketing audits' and gives an example question. While it doesn't explicitly state when not to use, the purpose is well-defined and implies single-entity checks should use ai_visibility_check instead.

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

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

Annotations provide readOnlyHint and idempotentHint, but the description adds significant behavioral context: it fans out across two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list if it times out. 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 somewhat lengthy but each sentence adds unique information: composite nature, usage context, return details, ecosystem scope, and failure behavior. It is front-loaded with the core purpose. A slight improvement could be tightening phrasing, but overall it is 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 composite tool with two services and simple parameters, the description covers usage, return values, and edge cases (partial failures, timing). It lacks mention of authentication or rate limits, but annotations indicate read-only. Given the complexity, it is largely complete, though an explicit listing of return fields would be beneficial.

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

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

The input schema has 100% description coverage for parameters. The description adds value by noting that scoped packages are accepted for 'package' and that version defaults to latest when omitted. It also describes the return structure (summary block, advisories, etc.), which is not in the schema.

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

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

The description clearly states the tool performs a composite check for evaluating npm packages, combining deps.dev and bundlephobia data. The verb 'scan' and resource 'dependency' are explicit, and it distinguishes itself from siblings by specifying NPM ecosystem scope and the combination of data sources.

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 use this tool when an agent asks about safety, popularity, size, or cost of adding an npm package. It also notes that other ecosystems (PyPI, Maven, etc.) fall under a different tool (deps.dev:version directly), providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is clear. The description adds that it's client-side (performance context), and that contract prices are implied probabilities (data interpretation). This adds behavioral value 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?

Three concise, front-loaded sentences with no fluff. Every sentence adds distinct and important context.

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 explains the market scope and probability interpretation, but does not describe the output format (e.g., fields returned). For a search tool without output schema, a brief note on what the results contain would improve completeness.

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 description adds 'case-insensitive substring' for the query parameter and 'default 15, max 30' for limit, which extends the schema's baseline descriptions. Schema coverage is 100%, but the description still provides useful nuance.

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

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

The description clearly states the tool searches PredictIt markets by name, specifies it's client-side over ~250 markets, notes US-politics focus, and mentions keyless access. This distinguishes it from siblings like get_market and list_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 explains that this tool is needed because PredictIt has no search endpoint, implying it's the way to search by name. It implicitly contrasts with list_markets for full lists, but does not explicitly state when not to use it.

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

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

Goes beyond annotations by describing embedding model, window size, char cap with truncation flag, and return structure (passages, offsets, scores). No contradiction with annotations.

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

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

Front-loaded with core action, then usage context, then technical details. Every sentence adds value; no filler. About 5 sentences, well-structured.

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

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

For a tool with no output schema, description explains return values (passages, offsets, similarity scores), limits (200K chars capped), and embedding details. Pairs with a sibling, providing workflow context. 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?

All parameters are described in schema. The description adds value by giving example queries for the 'query' parameter and clarifying the 'text' is a fetched record. Schema coverage is 100%, so baseline 3, extra examples push 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 performs semantic search inside a previously fetched record, using a specific verb ('search within') and resource ('source'). It distinguishes itself from siblings like search_markets or deep_research by focusing on a record already in hand, not external search.

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 the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for grounded generation. It does not explicitly exclude other cases but provides clear 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 indicate a mutable, idempotent, non-destructive creation. The description adds critical behavioral details: returns new subscription id, requires OAuth (anonymous/BYO cannot persist), type-specific parameters, delivery options (feed always on, optional email/sms/webhook with constraints like SMS cap of 10/day and webhook auto-disable after 10 failures), and webhook signing explanation. 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 detailed but well-structured with clear sections (supported types, delivery channels, examples). It could be slightly more concise by trimming some examples, but the structure helps readability and the information density is justified.

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 explicitly states the return value (new subscription id). It covers all necessary prerequisites, type-specific parameters, delivery options with constraints, and behavioral outcomes (webhook auto-disable, SMS cap). This provides a complete picture for correct tool 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% (all parameters described). The description adds substantial meaning beyond the schema: detailed examples for each type (sec_8k with item codes, polymarket_edge with topics, fred_series with series_id, etc.), delivery channel specifics (webhook signing, SMS verification, auto-disable), and constraints (phone verification, rate limits). This greatly aids correct parameter construction.

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 creates a proactive monitoring subscription to a live-data event stream, specifying the verb (Create), resource (subscription), and context (live-data). It distinguishes 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 explicitly requires a Pipeworx OAuth account and lists supported types and delivery channels with examples, providing clear context for when to use each. It lacks explicit 'when not to use' or alternative tool mentions, but the guidance is strong enough for correct selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds value by explaining the output format (category-bucketed examples with tool+argument shapes) and the open-world nature (drawn from a live catalog of thousands of tools). 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 reasonably concise for the amount of information conveyed. It front-loads common user queries and then provides structured details. A slight reduction in length could be possible, but 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 the tool's role as an onboarding entry point with many siblings, the description is thorough. It covers what the tool returns, how to use the parameter, and when to invoke it. No output schema exists, so the description fully handles the explanatory burden.

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 clear description of the optional topic parameter. The description adds meaning by listing example values (finance, pharma, etc.) and explaining the effect of omission vs. inclusion, which goes beyond the schema's brief description.

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

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

The description explicitly states the tool is an 'onboarding entry point' that returns 'category-bucketed example questions' to help users understand what Pipeworx can do. It lists specific categories (e.g., company financials, drugs, economics) and distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on idea generation.

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 guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains the optional topic parameter ('omit for a full spread, or pass topic...to focus') and hints at alternatives implicitly through the sibling 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 indicate idempotent and non-destructive. Description adds the important detail that the row is deactivated (not deleted) and ownership is enforced, which is valuable 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?

Two concise sentences with no waste. Front-loaded with the main action, then key constraints. 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 one required parameter, no output schema, and annotations covering safety, the description is fully complete for this tool. It explains the effect (deactivation vs. deletion) and ownership, which is all an agent 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 coverage is 100% with 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds 'by id' but doesn't provide additional meaning beyond what the schema already conveys.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscriptions). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by its specific verb and id parameter.

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: ownership enforcement and soft deactivation behavior. It doesn't explicitly mention when to use vs. alternatives, but the purpose is sufficiently clear 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, idempotentHint, and destructiveHint. The description adds substantial behavioral context: the domain (company-financial claims), data sources (SEC EDGAR + XBRL), return verdict types, and its efficiency benefit over multiple sequential calls. No contradiction with annotations.

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

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

The description is a single concise paragraph that front-loads query patterns. It is efficient but could be slightly more structured (e.g., bullet points for return types). Still, it delivers key information without 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?

Given the simplicity of the tool (one parameter, no output schema, rich annotations), the description fully covers what an agent needs: scope, sources, return format, verdict types, and efficiency. 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?

The schema covers the single 'claim' parameter with 100% description coverage. The description adds context about the type of claims supported but does not provide new syntactic or format details beyond what the schema offers. 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 uses specific verbs like 'verify', 'confirm or refute', and provides natural-language examples that clearly define the tool's purpose. It distinguishes itself from sibling tools by focusing exclusively on fact-checking company-financial claims via SEC EDGAR + XBRL.

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 ('Use whenever the agent needs to check whether something a user said is factually correct'). However, it does not mention when not to use it or list alternative tools for non-financial claims, leaving a minor gap.

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