Helsinki Events

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: scoring range, model defaults, BYO key for Anthropic, per-model return structure (score, confidence, signals, raw_response). No contradictions with annotations.

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

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

The description is concise (3 sentences) and front-loaded with the tool's main function, then adds details about models and return format. Every sentence contributes value without redundancy.

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

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

Given 4 parameters, no output schema, and no nested objects, the description adequately covers return format (per-model {score, confidence, signals, raw_response} + combined view) and usage scenarios. It provides sufficient context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% with all 4 parameters described in the input schema. The description rephrases some parameter details (e.g., default model, API key usage) but adds minimal new meaning beyond the schema's inherent descriptions. 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 probes LLMs for knowledge about an entity and scores visibility (0-100) per model, with a specific verb (probe) and resource (LLMs). It distinguishes from siblings by focusing on AI visibility audits, unlike comparable tools like 'ask_pipeworx' or 'deep_research'.

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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and gives context for when to use the tool. However, it does not explicitly state when not to use it or compare directly to similar sibling tools like 'scan_competitor_ai_presence', so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds that it routes to multiple tools, returns citations, and is fast. No contradictions, and it provides useful context 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?

Description is long but front-loaded with key guidance. Every sentence adds value (use cases, alternatives, examples). Could be slightly more concise, but the length is justified by the depth of guidance.

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

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

For a complex tool that routes to many sources, the description is highly complete: includes when to use, what it does, examples, constraints (e.g., no web search for certain categories), and sibling distinctions. No output schema, but the description hints at structured answers with citations.

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 6 parameters all as aliases for 'question', with 100% description coverage. Basic examples are given in schema. Description does not add parameter-level detail beyond the schema, but the schema already covers meaning adequately.

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

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

Description clearly states 'PREFER OVER WEB SEARCH' and enumerates specific data domains (SEC filings, FDA, etc.). It explains it routes to 4,862 tools and returns structured answers with stable citation URIs, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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 when to use this tool (most factual questions) and when to step up to ask_pipeworx_grounded (hallucination-resistant single answer) or deep_research (multi-part questions). Also notes it's the default entry point and works on every tier.

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

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

Adds significant context beyond annotations: describes return format with evidence, refusal reasons, and cost of extra LLM call. Annotations already indicate readOnly, but description elaborates on non-inventiveness and refusal behavior.

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

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

Description is long but every sentence adds value: first sentence states purpose, then explains process, return format, usage guidance, and cost. No redundancy, 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 details the return format and refusal reasons. Covers all necessary context given the tool's complexity and rich annotations.

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

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

Input schema has 100% coverage with aliases all described as equivalents to 'question'. The tool description doesn't add parameter-specific details but the usage guidelines clarify the kind of questions suitable. Baseline is 3 for high coverage, but extra context merits a 4.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and differentiates from sibling ask_pipeworx by noting extra cost and use case for quoted/cited answers. It also explains the process of routing, data fetching, and extraction using only tool results.

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, and the agent must not invent facts' and when not: 'prefer ask_pipeworx for casual lookups.' Also provides examples of high-stakes domains.

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

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

The description extensively discloses behavioral traits beyond annotations: fan-out patterns per category, response shapes with exact fields, error handling (GDELT 429s, fallback mechanisms), safety gates (low-confidence short-circuits, closed/inactive markets), and resolution-rule risk (flat-50¢ void settlements). This goes well beyond the annotations' readOnlyHint and idempotentHint, providing agents with full operational expectations.

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

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

The description is very long and contains detailed examples, fan-out tables, and response shape definitions. While this information is necessary given the tool's complexity, the description could be more structured (e.g., using bullet points) and some redundancy exists (input types repeated in first sentence and parameter description). It is comprehensive but not concise.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (result.market, result.analysis, result.evidence), resolver contract, parent_event extractor, news fields, and all edge cases. It covers both normal and error scenarios, ensuring the agent understands every aspect of the tool's behavior and output, making it fully complete for reliable usage.

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

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

Schema coverage is 100%, and the description adds meaningful context: for 'depth', it explains 'quick = 2-3 evidence sources, thorough = full fan-out' and the default; for 'include_raw', it clarifies the tradeoff (response size vs. detail) and typical use cases. The description also reiterates input formats for 'market' with examples, reinforcing schema documentation.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and distinguishes from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on research and evidence gathering.

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 strong guidance on when to use (for any of the listed questions about a Polymarket bet) and how to interpret results (e.g., 'ALWAYS inspect these before trusting the analysis block'). It does not explicitly state when not to use or compare to alternatives, but the detailed examples and edge-case handling (low-confidence, closed markets, wide spreads) give clear context for proper usage.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) already indicate safety and non-destructiveness. Description adds: pulls latest 10-K from SEC EDGAR/XBRL, handles off-calendar fiscal years, uses FAERS for drugs, returns sorted results by primary metric, and includes 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 pack with information but front-loaded with example queries. Every sentence adds value. Slightly verbose but justified given the complexity. Could trim redundant phrasing.

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

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

Given no output schema, the description adequately explains return type ('paired data + pipeworx:// citation URIs') and data sources per type. Covers edge cases (off-calendar fiscal years) and performance benefit (replaces 8–15 lookups). Sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100%, with descriptions for both parameters. Description adds meaning: explains that 'type' determines data source (SEC filings vs FAERS) and that 'values' expects tickers/CIKs for companies or drug names. Also notes results sorted by primary metric, which aids interpretation.

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 specifies the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one call. It lists example queries and distinguishes from sequential lookups and presumably single-entity tools like 'entity_profile'.

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

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

Explicitly states to prefer this tool over sequential single-entity lookups when comparing. Provides context on when to use (comparison, ranking). Could add explicit when-not (e.g., for single entity, use entity_profile), but overall strong 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are complemented by detailed behavioral traits: account requirement, depth-level behavior (gap recovery, contradiction scan), error cases (empty gaps), timing expectations, and citation formats. 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?

Long but every sentence serves a purpose: account requirement, sibling tool comparison, behavioral detail, timing estimates. Front-loaded with prerequisites. Could be slightly more structured but highly efficient for the information density.

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

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

No output schema, so description fully specifies return format: findings packet with evidence, confidence, source, fetched_at, pipeworx:// citation, gaps array, contradictions for thorough mode. Also covers differences between depth levels and edge cases (e.g., gaps[]), making the tool completely understandable.

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

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

Schema coverage is 100%, providing baseline 3. Description adds meaningful detail beyond enum labels: explains the meaning of each depth value ('quick=3 facets single hop', 'standard=5 with gap recovery', 'thorough=8 with contradictions') and confirms question is natural language. This justifies one point above baseline.

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

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

The description clearly states it performs multi-source grounded research across 1272 structured data sources, decomposes questions into facets, and runs parallel tool calls. It distinguishes from ask_pipeworx (single lookup) and bet_research, making the tool's unique role explicit.

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

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

Provides explicit guidance: use for broad/multi-part questions over structured data; avoid for breaking news or single lookups. Offers alternatives (ask_pipeworx) and prerequisite about account tiers. Clear when-not and 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?

Description adds that results include 'names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' Annotations (readOnlyHint, idempotentHint) are consistent. No contradiction.

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

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

The description is concise (three sentences) and well-structured: purpose first, then domain list, then return format and usage advice. Every sentence adds value without redundancy.

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

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

Given 6 parameters, full schema coverage, no output schema, and a large sibling set, the description covers tool purpose, usage guidelines, return format, and parameter context comprehensively. It even provides schema examples, making it self-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% with descriptions for all 6 parameters. The description adds value by explaining 'query accepts natural language description' and giving examples, plus noting aliases. This goes slightly beyond the schema, justifying a 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 states 'Find tools by describing the data or task' and lists specific domains (SEC filings, FDA, etc.). It distinguishes from sibling tools by advising 'Call this FIRST' to discover options, which sets it apart from other tools like deep_research or entity_profile.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for: [list]' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly defines when to use and implicitly when not to.

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

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

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. The description adds context: fans out across multiple sources, returns specific data fields, notes patents soft-fails after May 2025, and mentions GDELT→GNews fallback. No contradiction with annotations.

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

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

The description is dense but not overly verbose. It packs a lot of information into a single paragraph, which is acceptable. Slight improvement could be breaking into lists, but it's not excessively long.

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, fallbacks, parameter constraints), the description is comprehensive: it lists all data sources, explains return fields, notes limitations (patents sunset, name unsupported), and provides usage context. No output schema exists, but description adequately covers what the tool returns.

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 value by explaining that type is limited to 'company' and that value can be ticker or CIK (not names), which matches and slightly extends 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 explicitly states the tool provides a 'full cross-source profile of a US public company', lists example queries, and enumerates specific data sources and returned fields (CIK, filings, fundamentals, patents, news, LEI). It distinguishes from sibling tools like resolve_entity.

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

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

The description advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and explicitly warns that names are not supported, directing users to resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide read-only, idempotent, non-destructive. Description adds language fallback behavior and return fields, enriching transparency beyond annotations.

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

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

Two sentences, no wasted words. Front-loaded with action and location, then filters and output summary.

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

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

Describes return fields (venue, coordinates, tags) despite no output schema. Could mention pagination or default sorting, but sufficient for standard usage.

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

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

Schema coverage is 100% with good descriptions. Description summarizes filters but does not add new meaning beyond schema. Baseline 3 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?

Specific verb 'Find upcoming events' with precise location 'Helsinki, Finland' and data source 'City of Helsinki Linked Events'. Clearly distinguishes from siblings which are broad research or betting 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?

Context is clear for Helsinki events, but no explicit guidance on when to use vs alternatives or when not to use. Implied usage only.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds no new behavioral traits beyond what is obvious (delete is destructive). Could mention irreversibility or permission requirements.

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 short sentences with zero waste. Every sentence adds value: action, usage guidance, and sibling 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 tool with one required parameter and no output schema, the description fully covers what the tool does, when to use it, and context with siblings. No gaps.

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

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

Schema coverage is 100%, and the description's parameter explanation ('Memory key to delete') adds no meaning beyond the schema's own description. Baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', using the specific verb 'Delete' and identifying the resource 'memory'. This distinguishes it from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', providing context for alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it fetches a page and outputs markdown, which provides limited additional context beyond the annotations.

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

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

The description is two sentences long, front-loaded with the purpose and value, and every sentence adds useful information with no waste.

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

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

Despite lacking an output schema, the description explains the output format ('standard llms.txt markdown', 'single text blob') and covers all aspects: behavior, parameters, use cases. Annotations cover safety. Complete for this tool's complexity.

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

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

Schema description coverage is 100% for both parameters (url and max_links). The description does not add new details beyond what is already stated in the schema, 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 generates an llms.txt file for a given URL, detailing the process (fetch page, extract content, emit markdown). It is distinct from sibling tools like scan_competitor_ai_presence or ai_visibility_check.

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

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

The description explicitly lists three use cases (client indexing, own project drafting, competitor auditing) but does not include when not to use or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. Description adds value by specifying return fields and default active-only behavior, though does not mention pagination or limits.

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 states purpose and return fields, second gives usage guidance. No fluff, front-loaded.

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

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

For a simple list tool with one parameter and no output schema, the description covers purpose, return fields, and usage scenarios completely. No apparent gaps.

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

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

Schema description coverage is 100% with a clear parameter description. The description reinforces the parameter's purpose but does not add new meaning beyond the schema.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, lists return fields, and distinguishes from sibling tools like subscribe/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 mentions using this to review monitoring before adding more subscriptions or to find an id to cancel, providing clear context for use. Lacks explicit when-not-to-use but sufficient given sibling context.

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

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

Annotations are non-informative (all false), so the description carries the full burden. It discloses rate limiting ('5 per identifier per day'), billing ('Free; doesn't count against your tool-call quota'), and the team's response behavior. This provides valuable behavioral context beyond what annotations offer, with 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 5 sentences, front-loaded with the primary purpose, then usage guidelines, then behavioral details. Every sentence contributes a distinct piece of information with no redundancy or filler. Highly efficient.

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

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

For a simple feedback tool with 3 fully-described parameters and no output schema, the description covers all necessary aspects: purpose, when to use, parameter guidance (implicitly), rate limits, billing, and impact. No gaps for an agent to misinterpret or misuse 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema for the parameters; it only reiterates the enum categories for 'type' in the usage guidelines. The schema already provides detailed descriptions for 'type', 'context', and 'message'. Thus the description adds minimal additional semantic value.

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

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

Description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific categories (bug, feature, data_gap, praise) and distinguishes from other tools by providing usage context. The verb 'tell' with 'Pipeworx team' and the resource 'feedback' is specific and unambiguous.

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

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

Explicit when-to-use guidance is given: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states what not to do ('don't paste the end-user's prompt') and provides context on how feedback is used (team reads daily, affects roadmap). The usage boundaries are 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 readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: aggregation from analytics-engine, no PII, cached 5min-1h, and data structure. This provides transparency beyond annotations without contradiction.

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

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

The description is a single paragraph of around 100 words, front-loaded with the main action, then use cases, then technical details. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description covers input, output, caching, data source, privacy, and use cases. Missing explicit details on ranking or number of top items, but still highly 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?

The input schema has 100% coverage with a description for the window parameter. The tool description reiterates the window options and adds interpretation of shorter vs longer windows. Since schema covers the semantics, baseline is 3; the extra context is helpful but not essential.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. It uses specific verbs ('returns') and resource ('trending calls'), and differentiates from siblings like ask_pipeworx by focusing on aggregate trending data. The three listed use cases further clarify its purpose.

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

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

The description explicitly lists three scenarios when to use the tool (discovering hot data, confirming canonical tools, checking use case alignment). While it doesn't name alternative tools, the use cases imply when this is appropriate versus siblings like discover_tools or ask_pipeworx.

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

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

Annotations confirm read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: internal checks (monotonicity, partition, Jaccard similarity, partition filter, fill check), response structure, and conditions for trading (realizable_edge_pp). 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 detailed and well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). While slightly verbose given the complexity, every sentence adds value and the structure aids readability.

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

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

Despite lacking an output schema, the description thoroughly explains the response format (opportunities[] with fields, partition_check details) and covers edge cases (fill check, placeholder filtering). It also references a sibling tool for custom sizing, making it self-contained.

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

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

Schema description coverage is 100% with both parameters described. The description adds significant context: default behavior with no args, expected slug format, what topic does, and how modes differ. This adds value 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two operation modes (event and topic) with specific use cases, and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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

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

The description explicitly says to call with no args for a trending scan, pass event for a specific market, or topic for cross-event scanning. It provides recommendations (event recommended) and explains when to avoid trading (realizable_edge_pp ≤ 0). It lacks explicit 'when not to use' but gives good context.

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

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

The description extensively discloses behavioral traits: response structure (by_segment, fed_candidates, diagnostics), caching behavior ('Cached 1h at the KV level keyed on all knobs'), and edge case handling (e.g., partition arbs always have kelly_fraction_half=0 at parent level, fed candidates excluded from ranking). Annotations confirm read-only, idempotent, non-destructive; no contradiction.

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

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

The description is long but well-structured and front-loaded with the core purpose. Every sentence provides unique information. It uses numbered lists and clear groupings. Slightly verbose but appropriate for the tool's complexity; could be tightened without losing value.

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

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

Given 9 parameters, no output schema, and high complexity, the description fully compensates by explaining the output structure (three segments under by_segment, diagnostics), caching, parameter interactions, and caveats (e.g., fed markets unreliability). It leaves no significant gaps for an agent to misuse 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?

Schema coverage is 100% (all 9 parameters have descriptions). The description adds context beyond schema: explains tradeable-edge knobs (min_liquidity, max_spread_pp), defaults, and practical usage tips (e.g., slippage_pp notes 'Polymarket has zero trading fees... bid/ask + thin depth typically eats 20-50bp per trade'). This adds value, justifying a score above the baseline of 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 states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a clear use case ('what should I bet on today'). However, it does not explicitly distinguish from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so it loses a point for lack of differentiation.

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

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

The description implies a use case for finding betting opportunities but provides no explicit guidance on when to use this tool versus alternatives (e.g., polymarket_arbitrage for arbitrage opportunities). There are no exclusion criteria or alternative tool names mentioned.

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 behavior. The description adds significant detail: the response structure with tracked, expired, and snapshot_dates arrays; explanation that snapshots are written on cache-miss causing gaps; decay computed from daily closes. This goes well beyond the annotations.

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

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

The description is lengthy but well-structured: purpose, arguments, response fields, and limitations. It is front-loaded with the core telemetry question. A slightly more compact phrasing could improve conciseness, but it is organized logically.

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 return structure: tracked[] with fields like edge_pp_net time-series, trend, decay_pp_per_day; expired[] with lifespan_days; snapshot_dates[] with gap reasons. It also covers limitations like TTL and intraday vs daily data, making the tool's context 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?

With 100% schema coverage, the baseline is 3. The description adds minimal extra: confirms defaults (days: 14, window: 1wk) and clarifies 'window' as a snapshot family. The schema already provides these details, so the description does not significantly improve understanding.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' answering the specific question of how long an edge has existed and if it's shrinking. It contrasts with the sibling 'polymarket_edges' by focusing on temporal dynamics, making the purpose distinct and actionable.

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

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

The description explains when to use this tool: when needing to distinguish between fresh and old edges, as 'a fresh wide edge and a 3-week-old wide edge are different trades.' It also provides limitations like TTL and non-intraday data. It lacks explicit alternatives but the context implies this is for temporal analysis.

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, idempotent, and non-destructive. The description adds rich behavioral detail: walks the ladder, returns verdict (clean/degraded/cannot_fill), warns about forced directional risk, and explains how basket fills can strand user unhedged. All consistent with annotations, no contradictions.

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

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

The description is long but well-structured with section headers (SINGLE-MARKET, BASKET) and front-loaded purpose. Every sentence adds value, though some details could be more compact. Still highly readable and efficient.

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

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

Even without an output schema, the description enumerates all return fields for both modes, including edge cases (thin_legs, forced_directional_risk, cannot_fill). It covers error conditions and usage limitations comprehensively. No gaps for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for all parameters. The description further clarifies default behavior (side defaults, size_usd interpretation for single vs basket, auto side for basket). Adds semantics beyond the schema, such as clamp range and that size_usd is settlement notional in basket mode.

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

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

The description clearly identifies the tool as a realizability check against live order-book depth, with two explicit modes (single-market and basket). It specifies the exact purpose: comparing theoretical vs realizable edge, which distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Provides reasoning about thin books and partial fills converting arbs into directional risk. No ambiguity about context.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description goes far beyond by detailing compatibility_warning conditions, temporal alignment checks, and skipped cross-type/subtype counters. This provides deep behavioral context for the agent.

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

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

The description is dense but front-loaded with purpose and modes. While lengthy, every sentence adds value. Could be slightly more concise, but structure is clear and information-rich.

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

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

Despite lacking an output schema, the description fully specifies the response structure (leg-by-leg prices, matched spreads, safety fields). All aspects of the tool's behavior are covered, making it 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 coverage is 100% with descriptions for each parameter. The description adds significant meaning beyond the schema by explaining the topic macro shortcuts and how explicit overrides work, including examples and behavioral nuances.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like 'polymarket_arbitrage' by specifying the two-venue 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?

Two explicit modes (topic shortcuts and explicit tickers) are documented, with examples for each. The description also warns that most pre-mapped topics may not return tradeable spreads, guiding the agent toward explicit pairings. No direct comparison to sibling tools, but the context is clear.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds scoping to identifier and pairing with remember/forget, going beyond annotations.

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

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

Three sentences pack all essential info: action, use case, scope, and pairing. No wasted words.

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

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

For a simple lookup tool with no output schema, the description covers return behavior (value or list), scoping, and related tools. Complete.

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

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

Schema coverage is 100% (one parameter 'key' with description). Description adds examples but does not significantly extend 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 the tool retrieves a specific value or lists all keys, with concrete examples like 'user's target ticker'. It distinguishes from siblings by naming 'remember' and 'forget' as paired tools.

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

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

Provides context for when to use: 'look up context the agent stored earlier' and describes behavior for omitting key. Does not explicitly list alternatives among siblings, but the context is clear.

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

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

Although the description discloses mark_read behavior (flagging events as read), this contradicts the annotation readOnlyHint=true which implies no state modification. The description adds behavioral context but introduces inconsistency.

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 in a single paragraph, no wasted sentences. It front-loads the main purpose and then details parameters and usage. Could be slightly more terse 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?

Despite no output schema, the description explains the returned fields (source, citation_uri, raw payload) and gives context about polling, feed persistence, and an alternative REST endpoint. This makes the tool usage clear and 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?

The schema covers all 5 parameters with descriptions, but the tool description adds context on how each parameter affects behavior (e.g., mark_read:true flags events read, limit max, since as ISO timestamp). This adds value 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 pulls fired events from subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes itself from siblings like 'events' by focusing on subscription feed alerts.

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

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

The description provides explicit filtering options (type, since, mark_read, unread_only) and mentions polling is fine. It also notes an alternative REST endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools like 'events'.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint=true, openWorldHint=true, etc.). It discloses the multiple data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), the fallback behavior ('GDELT preferred, GNews when rate-limited or 5xx'), the soft-fail situation (PatentsView API sunset May 2025), and the output structure. No contradictions with annotations.

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

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

The description is front-loaded with purpose and examples, then provides details. It is adequately concise but slightly long—every sentence adds value, though a minor reduction could be made. Still, it meets the criteria for efficient communication.

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 logic, parameter nuances), the description is remarkably complete. It explains the data sources, the fallback, the `since` format, the input types, and mentions the output structure ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). There is no output schema, but the description adequately covers the return values.

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 value by explaining the `since` parameter in context (e.g., 'Use "30d" or "1m" for typical monitoring'), clarifying that `value` accepts ticker or CIK, and noting that `type` currently only supports 'company.' This exceeds the baseline, justifying a 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 starts with concrete user query examples ('What's new with X', 'latest on Y') and clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly distinguishes from the sibling tool 'entity_profile' by specifying when to use the alternative ('Use entity_profile instead when you want the static profile'). This meets the criteria for specific verb+resource and sibling differentiation.

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

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

The description provides explicit guidance on when to use the tool vs. when not to, stating: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also gives example queries and explains the `since` parameter format with examples. This fully meets the criteria for explicit when/when-not and 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 provide idempotentHint and destructiveHint. Description adds crucial context: session scoping, persistence differences (authenticated vs anonymous), and 24-hour retention for anonymous. 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 efficiently convey purpose, usage, and behavioral details. The first sentence captures the core purpose. Could be trimmed slightly, but it's well-structured and front-loaded.

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

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

Given no output schema, the description covers the input semantics and persistence behavior. It doesn't mention error handling or confirmation of storage, but idempotentHint mitigates the need. Adequate for most agents.

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

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

Schema descriptions are clear (100% coverage) with examples for keys. Description reinforces the key-value concept and adds context about typical use cases. Could be slightly better by mentioning that the key can be overwritten.

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 saves data for reuse, specifies it uses key-value pairs, and distinguishes from siblings like recall and forget. The verb 'save' and resource 'data' are specific and actionable.

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 when to use: 'when you discover something worth carrying forward.' Also explains why (avoid re-lookup) and pairs with recall/forget. No mention of when not to use, but the guidance is strong.

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

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

The description adds behavioral context beyond annotations by noting that 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' This informs the agent of the tool's internal complexity and performance implications. Annotations already mark it as read-only, idempotent, and non-destructive, and the description does not contradict them.

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

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

The description is concise (about 4-5 sentences) and front-loaded with query examples immediately conveying the tool's purpose. Every sentence adds value, including details on supported types, typical use, and internal behavior. No redundant or unnecessary 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 has no output schema, the description compensates by thoroughly explaining what each entity type returns (e.g., ticker + CIK for company, RxCUI for drug). It also covers internal cascading behavior. For a tool with two required parameters and moderate complexity, the description provides complete context for correct invocation.

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

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

Schema coverage is 100% with descriptions for both parameters, but the tool description adds significant value by providing examples of accepted values (e.g., ticker, CIK, name for 'company'; brand or generic name for 'drug') and explaining output per type. This enriches parameter understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: to resolve user-spoken names to canonical identifiers. It provides concrete examples like 'What's the ticker for…' and specifies supported entity types (company, drug) with their respective outputs, making it easy to understand what the tool does. This distinguishes it from sibling tools by positioning it as the go-to for name-to-ID lookup.

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 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also details what each entity type accepts and returns. However, it lacks explicit when-not-to-use scenarios or alternatives if the tool fails, which would enhance the guidelines.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns confidence and signal density. No contradictions.

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

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

Four sentences, each contributing unique information: main function, how it works, use case, return format. Front-loaded with key action. 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?

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers parameters, usage context, and intentional design (first entity as subject). Complete for the tool's purpose.

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% (every parameter has a description). The description adds value by noting the first entity is treated as the subject for narrative purposes and that the entities array should be 2-8 items, which 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?

Description clearly states it compares AI visibility across multiple entities, using ai_visibility_check as a subroutine, and outputs a ranked comparison. It distinguishes 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?

Explicitly frames use case for competitive AI-marketing audits with a concrete example question. However, it does not explicitly state when to use an alternative tool like ai_visibility_check for a single entity, though the context strongly implies multi-entity use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds context about composite fan-out across services, partial failures degrading gracefully, and timing (5-30s for first measurement). 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 front-loaded purpose and subsequent details. It is somewhat lengthy but every sentence provides essential information (use case, ecosystem scope, failure behavior, return format). Could tighten slightly but overall efficient.

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

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

Given the tool's complexity (composite data sources, partial failures, timing concerns), the description covers all necessary context: return structure (summary block, advisories, links, alternative versions), behavior under failure, and ecosystem scope. No output schema exists, so description fully documents what is returned.

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. Description adds value beyond schema: clarifies default version behavior ('Defaults to the latest published version when omitted'), accepts scoped packages, and frames the 'version' parameter as optional.

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

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

The description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia data. It specifies the verb 'scan_dependency' and the resource 'npm package'. It distinguishes from siblings by being the only tool focused on package health/impact; no other sibling covers this domain.

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: 'when an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also states limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' Provides guidance on partial failures and timing.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description reveals embedding model, window size, char cap, truncation behavior, and return type with offsets, adding 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?

Two focused paragraphs: first covers purpose and usage, second adds technical detail. 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?

Despite no output schema, description explains return format (passages with offsets and scores) and technical limits (200K chars, overlapping windows), making it complete for a semantic search 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 has 100% description coverage, but description adds value by giving examples for query parameter and specifying the 200K char limit for text, enhancing 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 performs semantic search inside a fetched record, specifies the verb and resource, and differentiates from sibling tool ask_pipeworx_grounded by describing the pairing use case.

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

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

Explicitly states when to use ('when the record is too big to cram into the prompt') and mentions the paired alternative (ask_pipeworx_grounded), providing clear usage context.

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

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

The description extensively discloses behavior: returns subscription id, requires OAuth, explains type-specific params, delivery channels, SMS cap (10/day), webhook auto-disable after 10 failures, and HMAC signing. Annotations already indicate non-readOnly, non-destructive, idempotent, and openWorld, with 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 front-loaded with purpose and flows logically into types and delivery, but it is somewhat dense and could benefit from bullet points for readability. Every sentence adds value, though slightly lengthy.

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

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

Given the complexity (3 params, nested objects, multiple types, delivery options) and lack of output schema, the description covers return value (subscription id), all type configurations, delivery methods, and constraints (SMS cap, webhook secrets), making it complete for the 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%, but the description adds significant value by detailing each type's parameters with examples (e.g., sec_8k items, polymarket_edge topic), constraints (SMS cap, phone verification), and webhook HMAC mechanics, far 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 creates a proactive monitoring subscription to live-data event streams. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying the creation action and requirements.

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

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

The description explicitly requires a Pipeworx OAuth account and states that anonymous/BYO users cannot persist subscriptions, indicating when not to use. However, it does not explicitly compare to alternatives like list_subscriptions or unsubscribe for management tasks.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant value by detailing that the tool returns category-bucketed example questions with exact tool and argument shapes drawn from the live catalog. 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 thorough and front-loaded with key trigger phrases. While it is relatively long, all sentences serve a purpose (explaining output, usage, and alternatives) with minimal 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 has only one optional parameter, no output schema, and rich annotations, the description provides complete guidance: it explains the return structure, when to use it, and how to constrain the output. No gaps are apparent.

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 in the schema is identical to what the tool description provides. The description does not add new semantic information beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool is an onboarding entry point that returns categorized example questions with tool shapes. It lists multiple trigger phrases (e.g., 'what can I ask', 'give me ideas') and explicitly distinguishes itself from siblings like 'discover_tools' by recommending using this first to learn about Pipeworx capabilities.

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 this FIRST when you do not yet know what Pipeworx can do' and explains how to call it with or without the 'topic' argument. It provides clear context for when to use, though it does not explicitly state exclusions or 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?

Discloses that 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts', adding behavioral context beyond annotations (which only provide hints). Also mentions ownership enforcement.

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, front-loaded with the main purpose. Every sentence provides essential information without redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership constraints, and persistence behavior. No gaps identified.

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

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

With 100% schema coverage and a single parameter described as 'Subscription id (uuid) returned by subscribe', the description adds no additional meaning. Baseline 3 is appropriate as schema fully explains the parameter.

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

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

Description clearly states 'Cancel a subscription by id' – a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning cancellation and ownership enforcement.

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 is enforced — you can only cancel your own subscriptions', providing clear context on when to use. It does not explicitly mention alternatives but the ownership condition serves as a de facto usage guideline.

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 annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, indicating safe and idempotent behavior. The description adds significant context: the verdict types (confirmed, approximately_correct, etc.), the inclusion of structured form, actual value with citation, percent delta, and the fact that it consolidates multiple sequential operations. 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 slightly longer than necessary (4-5 sentences) but each sentence serves a purpose: triggers, usage, scope, output summary, and benefit. The structure is logical, starting with examples, then stating purpose, usage, limitations, output, and efficiency gain. It is well-organized but could be tighten slightly 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?

Given the single required parameter and lack of output schema, the description provides a comprehensive overview: what the tool does, when to use it, its limitations (company-financial), the output format (verdict, structured form, value with citation, delta), and its efficiency advantage. No gaps are apparent for the intended use case.

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

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

The input schema has 100% coverage with a single 'claim' parameter that includes a description and examples. The description reinforces this by providing alternative natural-language triggers and explaining the input style. While the schema already does a good job, the description adds value by framing the expected input as a natural-language factual claim and giving practical examples.

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 immediately lists natural-language triggers and defines the tool as 'natural-language claim verification against authoritative sources.' It clearly identifies the scope (company-financial claims via SEC EDGAR + XBRL) and contrasts with other tools, such as replacing 4-6 sequential calls. The verb 'validate' combined with 'claim' leaves no ambiguity about the action and resource.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies that the current version supports only company-financial claims, providing an implicit limitation. However, it does not explicitly list situations where the tool should be avoided or mention alternative tools for non-financial claims, preventing a score of 5.

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