Helsinki Events

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

The description adds substantial behavioral context beyond annotations. It explains that probing is non-destructive (consistent with readOnlyHint), that output includes per-model score, confidence, signals, and raw_response, and that using Anthropic requires a personal API key with direct payment. This addresses ethical and practical behavioral aspects not covered by annotations.

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

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

The description is concise (two main sentences plus a use-case sentence), front-loaded with the core action, and every sentence adds value. No wasted words or repetition of schema/annotations.

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 4 parameters all well-described in schema, no output schema, but the description details the return structure (per-model score, confidence, signals, raw_response plus combined view) and lists concrete use cases. This provides sufficient completeness for an AI agent to understand input, output, and applicability.

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 good parameter descriptions. The description adds value by explaining the default model (Workers AI Llama-3.3-70b free) and the purpose of _apiKey (pass-through to Anthropic, direct payment). It also clarifies that context disambiguates entities. This goes beyond the schema's structural descriptions.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses specific verbs and resources, and distinguishes from siblings by specifying the domain (AI visibility scoring) and mentioning use cases like competitive monitoring, which sets it apart from similar tools like scan_competitor_ai_presence.

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

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

The description provides clear guidelines on when to use the tool's options: default model is free, pass _apiKey for Anthropic (BYO key). It implies the tool is for audits and monitoring but does not explicitly state when not to use this tool or compare it to direct siblings like scan_competitor_ai_presence. However, the provided context is sufficient for effective use.

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

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

The description adds behavioral context beyond annotations: routes to one of 5245 tools, returns structured answer with stable citation URIs, says it 'fills arguments' automatically, and notes it's fast and works on all tiers. Annotations already indicate read-only and idempotent, so transparency is well-supported. 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 relatively long but front-loaded with the key preference statement and packed with useful examples and usage context. While every sentence adds value, it could be slightly more concise without losing essential details.

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

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

Given the tool's complexity (routing to many sources) and the absence of an output schema, the description provides sufficient context: what it returns (structured answer with URIs), when to use, and how it compares to siblings. Missing a precise output format description, but otherwise complete.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds examples and mentions alias names, but does not add significant semantic meaning beyond what's in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: answer factual questions using authoritative structured data with citations, and explicitly distinguishes it from web search and sibling tools. It lists many specific data types (SEC filings, FDA drugs, etc.) and provides concrete examples, making the purpose unmistakable.

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

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

The description provides explicit guidance on when to use (prefer over web search for factual questions, with examples) and when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). It also mentions that it works on every tier and is a fast single call, giving clear context for 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 indicate safe, read-only, idempotent behavior. The description adds that it's a full working router with no fallback, explaining the experimental nature and the current state (no active candidate). 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?

Reasonably concise, but includes some historical detail (last retired candidate date) that may not be essential. Front-loads the beta identity and relationship to ask_pipeworx effectively.

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

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

Given the tool's complexity as a router to thousands of tools, the description covers its relationship to stable version, experimental nature, current state, and fallback behavior. No output schema needed as response shape is identical.

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

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

Schema coverage is 100% with all parameters as aliases for 'question'. The description does not add new meaning beyond the schema, but the schema is clear. Baseline 3 is appropriate.

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

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

The description specifies that it is a beta version of ask_pipeworx with identical routing capabilities, serving as the experimental edge. It clearly states it's a universal router for 5,245 tools, distinguishing it from the stable ask_pipeworx.

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

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

Explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router. It also clarifies that currently no candidate is active, so it's identical, giving concrete guidance on when to use.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the extraction process using ONLY tool results, the explicit refusal reasons (not_in_source, no_tool_match, etc.), and the return format. Adds significant context about refusal behavior and cost.

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

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

The description is moderately long but well-structured, front-loading purpose. Every sentence adds value (process, return format, use cases, trade-off). Could be slightly more concise, but appropriate for the tool's complexity.

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

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

Given the tool's complexity, no output schema, and many sibling tools, the description covers purpose, usage guidelines, behavioral details, return structure, and explicit comparison to ask_pipeworx. It is fully complete 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 description coverage is 100%, so the schema already describes parameters. The description adds that the question is used for routing and filling arguments, which is contextual but doesn't add new parameter-level semantics beyond the schema's aliases list.

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

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

The description clearly states the tool provides a 'hallucination-resistant answer mode for high-stakes reads' and specifies it extracts answers using only tool results. It distinguishes itself from the sibling 'ask_pipeworx' by noting the extra cost and refusal behavior.

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: 'whenever an answer will be quoted, cited, or acted on' for high-stakes domains (financial, legal, medical). Explicitly recommends preferring ask_pipeworx for casual lookups, and mentions the cost trade-off.

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. Description adds extensive behavioral details: resolution contract (match confidence, alternatives, suggestions), parent event extractor, news fallback, safety short-circuits for low confidence and closed markets, wide spread handling, and cancellation rule parsing. 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?

Description is verbose and dense, with structured sections (RESOLVER CONTRACT, etc.), but could be more concise. Some details could be moved to schema or omitted without losing clarity.

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 lack of output schema, the description comprehensively covers return structure, evidence keys, market match behavior, parent events, news fallback, safety mechanisms, and resolution rules. All edge cases are addressed.

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

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

Schema coverage is 100% with well-described parameters. Description provides context but doesn't add significant new meaning beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and examples. It distinguishes from sibling tools by focusing on research and evidence gathering for bet evaluation.

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 use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides examples of fan-outs for different bet types. Lacks explicit when-not-to-use or alternatives, but the specificity compensates.

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, open-world behavior. The description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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 dense but well-structured: examples, usage preference, per-type data details, sorting, and return format. Each sentence adds value, though it could be slightly trimmed without losing meaning.

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

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

No output schema, so the description must explain return values, which it does: paired data plus citation URIs. It covers entity types, data sources, sorting, and the number of replacements (8–15 sequential lookups). Everything an agent needs to know is included.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant nuance: explains what data each enum value pulls and gives concrete examples for the values parameter (tickers/CIKs for company, drug names). 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 performs side-by-side comparison of 2–5 companies or drugs, with specific verbs like 'compare', 'rank', and examples that distinguish it from other tools like entity_profile. It cuts through ambiguity with concrete 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 instructs to prefer over sequential single-pack lookups when comparing entities, gives concrete query examples, and implies alternatives (entity_profile for single entities). The guidance is actionable and clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, true, and destructiveHint false. The description adds extensive behavioral context: account requirement, execution times (15-60s, up to 90s for thorough), gap recovery, contradictions, hop field, citation URIs, and semantic excerpting. 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 long but well-structured with front-loaded critical info (account, alternative, then details). Every sentence adds value, though could be slightly more concise. Still efficient for the complexity.

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

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

Despite no output schema, the description thoroughly explains return contents: findings packet with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field. Also covers semantic excerpting and stable citations. Complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds detail: 'depth' parameter explained with facet counts and capabilities (quick=3, standard=5+gap recovery+contradictions, thorough=8+leads+contradictions). The 'question' parameter usage is clarified (broad/multi-part fine). This exceeds baseline.

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

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

The description specifies a specific verb ('deep research') and resource ('Pipeworx's structured data sources'), clearly distinguishing it from siblings like ask_pipeworx. It states it decomposes questions into facets and routes to 5,245 tools in parallel.

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 (broad/multi-part questions over structured data) and when not (breaking news, single lookups), with alternative tool recommendations (ask_pipeworx). Also mentions account requirement and plan limitations.

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, idempotentHint=true, destructiveHint=false, and description adds that it returns top-N most relevant tools with full schemas ready to call, no contradiction.

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

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

Description is comprehensive yet well-structured, front-loaded with purpose, and every sentence adds value without 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?

Given 6 parameters (mostly aliases) and no output schema, description clearly explains return format (top-N tools with schemas) and use case, making it complete 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% with descriptions, but description further clarifies aliases (task, q, search, description) and gives examples of natural language queries, adding value beyond schema.

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

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

Description clearly states it finds tools by describing data or task, lists many domains, and distinguishes itself by being a discovery tool for browsing options when many tools exist.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear context for use. Also lists scenarios like browse, search, look up, discover.

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 that it fans out across multiple sources, returns specific fields, and notes that the USPTO part soft-fails until reactivated. It also clarifies the entity type limitation. 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 front-loads with user query examples and states the core purpose in the first sentence. It is somewhat lengthy but every clause adds necessary detail. A slightly tighter structure could earn a 5.

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

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

For a tool with no output schema, the description gives a good mental model of return structure (cik, filings, fundamentals, patents, news, LEI). It covers limitations and data sources. Missing details on pagination or error handling, but sufficient for a read-only aggregated profile.

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 embedding examples (AAPL, 0000320193) and usage guidance (names not supported, use resolve_entity). This helps the agent form parameters correctly 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 starts with clear example queries ('Tell me about X', 'research Acme') and states 'full cross-source profile of a US public company'. It explicitly distinguishes itself from chaining single-pack lookups, making the purpose and scope 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 explicit when-to-use ('ALWAYS PREFER over chaining single-pack lookups when user asks for a holistic view') and when-not-to-use ('names not supported – use resolve_entity first'). It also names the alternative tool (resolve_entity).

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

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

Annotations already provide readOnly, openWorld, idempotent, non-destructive hints. Description adds that events come with venue, coordinates, tags, and language fallback (English/Finnish). 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 wasted words. Efficiently covers what, where, how, and return details.

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

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

With no output schema, description adequately explains return values (venue, coordinates, tags). Covers all input filters and language behavior. Complete for a read-only, idempotent tool.

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

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

Schema coverage is 100%, so description doesn't need to detail each parameter. It groups filters (keyword, free admission, date window) which adds context, but no additional syntax or meaning beyond schema.

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

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

Clearly states 'Find upcoming events in Helsinki, Finland' with specific verb+resource+location. Distinguishes from sibling tools which are not event-finding tools.

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

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

Mentions filters (keyword, free admission, date window) and return fields, providing clear usage context. No explicit when-not-to-use or alternatives, but not needed as siblings are unrelated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful behavioral context about clearing sensitive data and the purpose of deletion, which goes beyond the annotation hints.

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

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

Three concise sentences with no redundancy. Each sentence serves a purpose: action definition, usage conditions, and related tool 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?

For a simple destructive tool with one required parameter and good annotations, the description covers purpose, usage, and pairing. It could mention the return value or success indication, but overall complete for the complexity.

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

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

Schema coverage is 100% and the parameter description 'Memory key to delete' is clear. The description's phrase 'by key' adds no new semantic information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete'), the resource ('previously stored memory'), and the identifier ('by key'). It distinguishes itself from siblings by explicitly listing 'remember' and 'recall' as partners for pairing.

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

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

Provides explicit conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also guides pairing with related tools, giving clear when-to and when-not-to context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds concrete behavior (fetches page, extracts title/description/key links, emits markdown) and output format (single text blob). However, it omits details like error handling or performance implications.

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

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

The description is three sentences with no wasted words. It front-loads the core action and output, then lists use cases. Every sentence serves a purpose.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers what the tool does, how it works, and its output format. No additional information is needed for an agent to use it correctly.

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

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

Input schema has 100% description coverage for both parameters (url and max_links). The description adds no new semantic information beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file' for any URL, with specific verb+resource. It distinguishes from siblings by focusing on llms.txt generation, which is unique among sibling tools like scan_competitor_ai_presence or validate_claim.

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

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

Explicit use cases are provided: getting a client's site indexed, drafting for own project, or auditing competitor's AI visibility. While it does not list when not to use, the context is clear and the examples cover the main 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?

Description adds value beyond annotations by specifying return fields and that subscriptions are caller-specific. Annotations already indicate read-only, idempotent, and non-destructive behavior; no contradiction.

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

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

Two sentences: first covers purpose and output, second gives usage guidance. No wasted words, front-loaded with key information.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description is complete. It covers what the tool returns, its scope, and when to use it.

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

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

Schema coverage is 100% with a single parameter (include_inactive) fully described in the schema. The description does not add any additional meaning about the parameter, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). This is distinct from sibling tools like subscribe or 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?

Explicitly instructs when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and guides the agent to appropriate circumstances.

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 discloses rate limits (5 per identifier per day), cost (free, no quota count), and the team's daily review process. Annotations are all false and consistent with this behavior; 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 three sentences with no waste: first sentence states purpose, second explains usage scenarios, third adds constraints and team impact. Information is front-loaded and well-structured.

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

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

Despite no output schema, the description covers all necessary aspects: what feedback types are accepted, how to format it, constraints (rate limit, free), and what happens after submission. It is fully complete for a feedback 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 context: clarifies enum values for type, advises message format (specific, 1-2 sentences, 2000 chars max), and explains optional context parameters. This enriches understanding beyond the raw schema.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It distinguishes itself from sibling tools which are all query/analysis tools.

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

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

The description explicitly tells when to use the tool (bugs, features, data gaps, praise) and when not to (don't paste end-user prompts). It also mentions rate limits and that it's free, providing comprehensive usage 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that data is derived from CF analytics-engine, no PII, and cached 5min-1h, providing valuable behavioral context beyond annotations.

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

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

Two concise paragraphs, front-loaded with core purpose. Every sentence adds value: use cases, data source, caching. No fluff.

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

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

Given tool simplicity (one param, no output schema) and rich annotations, description covers purpose, use cases, data source, and caching. Minor gap: no explicit return format, but acceptable for this tool type.

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

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

Single parameter 'window' with enum and schema description. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', enhancing schema meaning.

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 returns top tools, packs, and call volume over a window, with specific verb 'returns' and resource 'trending data'. Distinguishes from siblings by focusing on collective agent activity.

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?

Lists three explicit use cases (discovering hot sources, confirming canonical tools, aligning use cases). No direct exclusions, but context signals show many siblings; description is self-contained and clear about appropriate scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral context: fill check with realizable edge, overround detection, semantic anchor for cross-event pairs, partition filter for placeholders, and explicit guidance on when not to trade. No contradictions.

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

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

The description is well-structured with clear sections for each mode, but it is verbose (multiple paragraphs). Every sentence adds value, but some details could be condensed. Front-loading of main purpose is good.

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 thoroughly explains the response format (opportunities array, partition_check object, fill_check details). It covers all modes, edge cases (placeholders, low similarity), and provides enough context for an agent to use the tool effectively.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning beyond schema: for event, it accepts full URLs; for topic, it provides example seed questions. It explains the effect of each parameter on mode behavior, which enhances clarity.

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

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

The description states exactly what the tool does: find arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (default, event, topic) with specific verbs and examples, clearly differentiating from sibling tools like polymarket_edges or polymarket_fill_risk.

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 each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also directs to polymarket_fill_risk for custom sizing, 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?

The description goes far beyond annotations by detailing caching (1h KV), response structure (by_segment with three segments), edge calculation (slippage, Kelly, 24h-move warning), filtering knobs, and diagnostics. It explains fed candidate exclusions and segment-specific behaviors. No contradictions with annotations.

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

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

The description is long but well-structured, front-loading the core purpose and then logically progressing through model families, edge details, knobs, and response format. Every sentence provides unique information, though some technical details (e.g., exact α values) could be condensed without loss. Still, given complexity, the length 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?

Despite no output schema, the description compensates by detailing the response structure (by_segment groups, fed_candidates, diagnostics) and edge metrics (edge_pp_net, kelly_fraction, market.liquidity, 24h-move warning). All parameter constraints and interactions are covered. The tool's complex behavior is fully documented.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial value by explaining each parameter's purpose, default, and practical implications (e.g., 'min_kelly: ensures opportunities are large enough to bet sensibly', 'slippage_pp: describes typical execution costs'). This transforms dry schema fields into actionable guidance.

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's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' with a clear use case 'what should I bet on today'. It distinctively differs from sibling tools by focusing on Pipeworx data disagreement and provides a specific verb (scan/return) and resource (top Polymarket 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 makes it clear this tool is for discovering opportunities without paging through hundreds of markets. While it doesn't explicitly state when not to use it or name alternatives, the context of sibling tools like polymarket_arbitrage and polymarket_edge_tracker implies differentiation. However, explicit guidance on trade-offs would improve clarity.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable behavioral details: trend types (new, widening, stable, decaying), decay computation, expired opportunities with lifespan, and snapshot gaps due to cache-miss. No contradictions.

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

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

Description is fairly long but well-structured: purpose first, then expected response format (tracked[], expired[], snapshot_dates[]), then limitations. Each sentence adds value. Could be slightly tighter 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, but description thoroughly explains the three arrays and their fields (edge_pp_net time-series, trend, decay_pp_per_day, lifespan_days). Covers limits (TTL, snapshot gaps) and edge cases. Adequately complete for a query tool.

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

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

Schema coverage 100%, so baseline 3. Description explains defaults and constraints (days: default 14, max 30; window: default '1wk') and clarifies 'snapshot family' meaning, adding value beyond schema descriptions. Also includes clamp range for days.

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

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

Description states a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers the question of historical edge duration and decay, distinguishing it from sibling polymarket_edges which likely provides current snapshots.

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?

Implies when to use: for analyzing edge persistence vs current data from polymarket_edges. Provides context about trade relevance ('fresh wide edge vs 3-week-old') and includes constraints (max 30 days, 60-day TTL). No explicit exclusions, but the difference 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?

Despite annotations covering safety, the description adds rich behavioral context: walks ladder, returns top_book/vwap/slippage, verdicts (clean/degraded/cannot_fill), basket mode returns capture_ratio, profit_usd, thin_legs, forced_directional_risk. No contradictions.

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

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

Well-structured with clear sections and front-loaded key info, but slightly verbose. Every sentence adds value, yet could be tightened without losing clarity.

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 thoroughly lists all return fields for both modes, explains verdict values, and covers edge cases like thin legs and directional risk.

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 contextual meaning: explains side defaults and auto-mode in basket, size_usd interpretation in both modes, and clarifies market vs event distinction beyond schema descriptions.

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

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

The description clearly states the tool checks realizable vs theoretical edge using live order book depth, and distinguishes it from siblings like polymarket_arbitrage and polymarket_edges by specifying it should be used before acting on their signals.

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 use before polymarket_arbitrage signals or polymarket_edges trades above $500, and warns about thin books and partial basket fills converting arbs into directional positions.

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

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

The description goes far beyond annotations by explaining the two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge cases like non-equivalent bet shapes and temporal misalignment. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavioral context.

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

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

The description is lengthy but well-structured, with front-loaded purpose, then modes, response, and safety fields. Every sentence adds useful information, though minor redundancy (e.g., 'pre-mapped ≠ tradeable') could be trimmed. Overall, it earns its length.

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

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

For a tool with 3 parameters and no output schema, the description is exceptionally complete. It details the output structure (leg-by-leg prices, spread array, top_spreads_pp), safety fields, edge cases (non-equivalent shapes, temporal misalignment, zero matches), and counters. This compensates fully for the 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 description coverage is 100%, providing baseline clarity. The description adds value by explaining the pre-mapped list for 'topic', giving examples, and describing how explicit tickers override topic-mapped sides. This goes beyond the schema by clarifying usage modes and parameter interactions.

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 calculates cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes from sibling tools like polymarket_arbitrage.

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

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

The description provides detailed context on when to use the tool and includes cautionary notes about compatibility warnings and temporal alignment. It explains that real spreads are rarer than the shortcut list suggests. However, it does not explicitly state when not to use or suggest alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping context and pairing with remember/forget, which adds value beyond annotations. No contradictions.

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

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

Two concise sentences. First sentence captures the core functionality. Second sentence provides usage context and scoping. No unnecessary words.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is complete: it covers both modes, scoping, and related tools. No gaps.

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

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

Schema description is 100% covered and already explains the key parameter (omit to list all). The description repeats the same information without adding new details. 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 explicitly states the verb 'Retrieve' and the resource 'value previously saved via remember', and distinguishes listing all keys as an alternative. Clearly separates from sibling tools remember and forget.

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

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

Provides clear context: 'look up context the agent stored earlier' with examples (ticker, address, research notes). Explains scoping to identifier. Lacks explicit when-not-to-use, but usage is well implied.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true, but the description introduces mark_read as a state-modifying feature (flagging events as read). This contradicts the read-only hint, causing confusion. While it adds details about returned fields and filtering, the contradiction undermines transparency.

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

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

The description is concise at four sentences, each serving a clear purpose: stating the tool's action, listing key return fields, explaining parameters, and noting alternative access. It is well-structured and front-loaded.

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

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

Given 5 parameters, no output schema, and annotations providing safety profile, the description covers core behavior, parameters, and usage context. It lacks detail on output format beyond mentioning fields, but overall is sufficient for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'mark_read' as flagging events read for future calls, and 'since' as ISO timestamp for filtering. This goes beyond the schema descriptions, justifying a score of 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 uses the specific verb 'Pull' and resource 'fired events from your subscription feed', clearly identifying the tool's function. It distinguishes itself from siblings like 'events' (broader) and 'list_subscriptions' (lists subscriptions, not events).

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

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

The description mentions that polls work fine and suggests an alternative endpoint for scripts, providing some context. However, it does not explicitly state when to use this tool over alternatives like 'events' or 'search_within', nor does it give exclusion criteria.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description explains parallel fan-out behavior, fallback logic (GDELT to GNews), soft-fail for patents, and the return structure (changes grouped by source, with counts 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 well-structured, starting with example queries, then explaining functionality, parameter usage, and sibling distinction. Every sentence is informative without redundancy.

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

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

Given the tool's complexity (multiple sources, fallback, no output schema), the description is quite complete, covering sources, return structure, and parameter formats. It could be slightly more detailed about the exact shape of the changes array, but it is sufficient.

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

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

Schema coverage is 100%, but the description adds value by explaining 'since' with examples and recommended values, clarifying 'value' accepts ticker or CIK, and noting that 'type' is limited to 'company'. This surpasses baseline 3.

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

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

The description clearly identifies the tool as a change feed for a company over a recent window, providing example queries and listing data sources (SEC, GDELT/GNews, USPTO). It distinguishes itself from the sibling tool 'entity_profile' by specifying that entity_profile is for static profiles regardless of window.

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

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

The description explicitly advises when to use 'entity_profile' instead, and provides context for the 'since' parameter. However, it does not cover situations where other sibling tools might be preferred, leaving some ambiguity.

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, the description discloses that memory is scoped by the agent's identifier, and distinguishes between authenticated users (persistent) and anonymous sessions (24-hour retention). This adds significant behavioral context that annotations alone do not provide.

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

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

The description is concise at three sentences. It front-loads the core action ('Save data...'), follows with usage guidance, and concludes with behavioral details and sibling links. No extraneous information.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers all necessary aspects: purpose, when to use, behavioral traits (scope, persistence), and integration with related tools. It is fully informative.

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 providing naming conventions for keys (e.g., 'subject_property', 'target_ticker') and clarifies that values can be any text. This enhances understanding beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: to save data for later reuse. It uses the specific verb 'save' and resource 'data' (key-value pairs). It explicitly distinguishes itself from sibling tools 'recall' and 'forget' by mentioning pairing with them.

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

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

The description provides explicit guidance on when to use this tool: when discovering something worth carrying forward (e.g., resolved ticker, target address, user preference). It also tells the agent not to look it up again and pairs with recall and forget for a complete workflow.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool cascades through multiple endpoints internally and returns specific fields plus citation URIs, enhancing transparency beyond the annotations.

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

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

The description is concise yet comprehensive, with well-organized sections for each type. Every sentence serves a purpose, and the structure is easy to parse.

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

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

Given no output schema, the description fully explains return values (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug) and covers all parameters. It is complete for a resolver tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by detailing accepted input formats per type (ticker, CIK, name for company; brand/generic for drug) and mentioning auto-disambiguation for company, 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 that the tool resolves user-spoken names to canonical identifiers, providing example queries and listing supported entity types (company, drug). It effectively distinguishes the tool from siblings by focusing on identifier resolution.

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 FIRST whenever you have a name but need an ID' and mentions it replaces manual lookups. However, it does not provide explicit when-not-to-use scenarios or direct comparisons with specific sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it probes each entity, ranks by score, and returns a ranked list. No contradictions and complements annotations well.

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

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

Two sentences, front-loaded with purpose. Includes example query. Every sentence adds value, no fluff.

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

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

No output schema, but description explains return structure (ranked list with score, confidence, signal density). Covers usage nuances like model selection and context disambiguation. Could mention entity count limits, but not critical.

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. The description adds beyond schema: explains first entity is treated as 'subject' for narrative, rest as competitors. Also clarifies default model behavior and purpose of context parameter.

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

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

The description clearly states it compares AI visibility across multiple entities, using ai_visibility_check, and returns a ranked list. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 case: competitive AI-marketing audits, with an example question. While it doesn't explicitly say when not to use, the context implies when to use, and sibling tools like ai_visibility_check are available for single probe needs.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context about partial failures: bundlephobia's first measurement on a new version can take 5-30 seconds and sources_failed will list it if it times out, with the rest still returning. It also describes the return structure, including a summary block and per-advisory details.

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

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

The description is a single dense paragraph that front-loads the key purpose. It contains necessary details but could be more structured (e.g., bullet points for the return fields). Still, every sentence adds value and the length is appropriate.

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 has no output schema, the description compensates by listing summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, etc.), mentions fallback for other ecosystems, and explains partial failure behavior. This provides complete context for an agent to correctly invoke the tool.

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

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

The input schema covers both parameters with 100% description coverage. The description adds that scoped packages are accepted and that version defaults to latest published version when omitted. This adds useful context beyond the schema, though the schema is already clear.

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

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

The description clearly states the tool is a composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes from siblings by specifying the npm ecosystem scope and noting that other ecosystems fall under `deps.dev:version` directly.

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 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also clarifies the npm-only scope and mentions alternatives for other ecosystems, providing clear guidance on when to use this tool versus others.

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

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

Discloses embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), and character cap (200K chars with truncation flag). Annotations already indicate read-only, idempotent, open-world; description adds further behavioral details 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?

Concise, front-loaded, and every sentence adds value. No unnecessary words. Well-structured with key details in efficient prose.

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

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

Despite no output schema, description covers return values (top-N passages with offsets and scores), along with limits and pairing advice. Complete for a semantic search tool of this complexity.

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

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

Schema coverage is 100%, and description adds meaningful context: explains text as fetched record, query with examples, limit with default value, and the 200K char limit for text. Goes beyond schema.

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

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

Clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with fetching the whole document.

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 mentions that it saves context, returns only relevant passages with offsets for verification. Also suggests pairing with another tool.

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

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

The description reveals behavioral traits beyond annotations: it is a creation (write) operation, and it details delivery channel behaviors (email/SMS/webhook), verification requirements, rate limits (10/day SMS), and webhook auto-disable after failures. This adds significant context beyond the annotations (readOnlyHint=false, destructiveHint=false). However, it does not clarify the idempotency indicated by idempotentHint=true (whether creating same subscription again returns existing ID).

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 starting with the primary action, then type-specific details, then delivery channels. It uses a bullet-like list format which is easy to parse. While it is somewhat lengthy, every sentence adds information and there is no redundancy. It could be slightly tighter but is effectively organized.

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

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

Given the tool's complexity (multiple types, delivery options, external dependencies), the description covers all essential aspects: prerequisites (OAuth account), type-specific parameters with examples, delivery channel behaviors and constraints, and it mentions the return value (subscription id). There is no output schema, but the description adequately covers the output. It is complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds rich meaning to each parameter. It explains each subscription type with concrete examples in the params object (e.g., sec_8k with ticker and items, polymarket_edge with topic). The delivery parameter is fully explained with constraints (phone verification, webhook signing, auto-disable). This goes significantly beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the verb (create), resource (subscription to live-data event stream), and distinguishes from siblings like list_subscriptions or unsubscribe by focusing on creation. The return value is also mentioned.

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: requires a Pipeworx OAuth account and lists supported subscription types with example filters. It also notes limitations (anonymous/BYO cannot persist subscriptions) and delivery constraints (phone verification, daily SMS cap, webhook auto-disable). However, it does not explicitly exclude use cases or compare with sibling tools, which keeps it from a 5.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds functional detail: returns category-bucketed examples with exact tool+argument shape, and that it draws from a live catalog. No contradictions. However, it doesn't add behavioral traits beyond what annotations hint, but still provides useful context.

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

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

The description is somewhat long but front-loaded with common user questions. Every sentence adds value, explaining purpose, usage, and output. Could be slightly tightened but remains efficient for its informative role.

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 the return format (category-bucketed example questions with tool+argument shapes). It covers all necessary aspects: when to use, what to expect, and how to customize. Complexity is medium but fully addressed.

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

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

Schema coverage is 100% with one optional parameter described. The description adds value by explaining that omitting topic gives a full spread, and lists valid focus areas (finance, pharma, etc.) beyond the schema. It also clarifies the behavior more concretely.

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

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

The description explicitly states it is the onboarding entry point for an agent that just connected and wants to know what is worth asking. It specifies the verb (returns) and resource (category-bucketed example questions) and distinguishes from siblings by naming meta-tools like ask_pipeworx, entity_profile, etc.

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

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

Clearly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools' and provides explicit alternatives (ask_pipeworx, entity_profile, compare_entities). Also explains optional topic filtering.

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 detailing ownership enforcement, deactivation behavior, and historical event availability. No contradiction with annotations.

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

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

Three sentences with no redundancy. Front-loaded with the action and essential details. 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?

For a single-parameter tool with annotations and no output schema, the description fully covers purpose, usage constraints, side effects, and data persistence.

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

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

Schema has 100% coverage with a clear description of the 'id' parameter. The description reinforces that the id is returned by subscribe, providing useful context but not adding substantial new meaning.

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 verb 'Cancel' and resource 'subscription by id', clearly distinguishing from sibling tools like 'subscribe' 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?

Explicitly states ownership enforcement (can only cancel own subscriptions) and that the row is deactivated, not deleted. Implicitly guides when to use this tool versus alternatives like recent_alerts.

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 readOnly, openWorld, idempotent, not destructive. Description adds context: two verification paths, returns verdict with evidence. Does not contradict annotations. Adds value by explaining the operational details beyond what annotations convey.

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

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

Description is somewhat lengthy with technical details (e.g., SEC EDGAR, XBRL, percent-delta math). While informative, it could be more concise. The core purpose is front-loaded with trigger phrases, but later sentences add bulk.

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 states what is returned: verdict, actual value with citation, reasoning. Explains two operational modes and replaces multiple calls. Comprehensive for a claim verification tool.

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

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

Schema coverage is 100% with descriptions. Description further explains the 'claim' parameter with examples and 'tolerance_pct' with its purpose and default. Provides additional context beyond the schema, like the default being implied by wording.

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

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

Description uses specific verbs and resources: 'natural-language claim verification against authoritative sources.' It distinguishes itself from sibling tools by focusing on fact-checking and provides trigger phrases. The two-path approach (SEC EDGAR for financials, grounded pipeline for others) adds clarity.

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 whenever the agent needs to check whether something a user said is factually correct.' Provides examples of when to use. Lacks explicit when-not-to-use guidance, but the context implies it's for factual claims only.

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