Data Dallas

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

Discloses external LLM probing, payment implications for Anthropic, and output structure. Annotations already indicate read-only/idempotent; description adds value by detailing the operational behavior without contradiction.

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

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

Two sentences with no wasted words: first sentence covers action and key details, second covers output and use cases. Front-loaded and efficient.

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

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

Given no output schema, description compensates by detailing return fields (score, confidence, signals, raw_response) and use cases. Covers all necessary aspects for a read-only probing tool with simple parameters.

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

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

Schema covers 100% of parameters with descriptions; the description reinforces by providing examples for entity and context, and clarifies _apiKey usage. Adds context beyond schema for models and key.

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 probes LLMs to score visibility for a given entity, with a specific output format and use cases. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on visibility scoring per model.

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

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

Provides clear when-to-use context (AI-marketing audits, brand checks) and how to use (default free model, optional paid via _apiKey). Lacks explicit when-not-to-use or alternative tool differentiation, but the context is strong.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds key behavioral details: routing logic, citation URI format, and that it fills arguments. 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?

Front-loaded with 'PREFER OVER WEB SEARCH', well-organized with categories, examples, and alternatives. Each sentence adds value without unnecessary verbosity. Highly efficient for its 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?

Given no output schema, the description appropriately mentions the structured answer with citation URIs and the scale of sources. Could optionally mention error handling or timeout, but sufficient for an AI agent to understand the tool's output and behavior.

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

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

Schema coverage is 100% and each alias is already described in the schema. The description mentions aliases but adds no new semantic meaning beyond what is in the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's core function: routing questions to 4,552 tools across 1160 verified sources and returning structured answers with citations. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, providing a strong purpose definition.

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 ('what is', 'look up', 'find', etc.) and positions it as the default entry point. Provides clear alternatives and when to step up (grounded, deep research), and mentions it handles breaking news via news feeds. Comprehensive and actionable guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context: routing, extraction mechanism, return format with refusal reasons, and extra cost. 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 relatively long but every sentence adds value. It front-loads the key concept and uses bullet-style details for return format. Could be slightly more concise, but overall well-structured for a tool with complex behavior.

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

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

No output schema exists, but the description thoroughly explains the return format (answer, evidence, confidence, etc.) and failure modes. It differentiates well from siblings and provides enough context 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 6 parameters (all aliases for question). The description adds value by explicitly listing aliases and confirming natural language input, which the schema's descriptions also do but the description consolidates nicely.

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' with specific verb ('answer') and resource ('Pipeworx grounded answers'). It distinguishes from sibling 'ask_pipeworx' by noting the extra LLM call and refusal mechanism.

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

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

The description explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples (financial verdicts, legal claims). It also gives a clear alternative: 'prefer ask_pipeworx for casual lookups.'

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

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

The description goes far beyond the annotations (readOnlyHint, etc.) by detailing numerous behavioral aspects: fan-out examples for different bet types, response shapes (market, analysis, evidence), resolver contract, parent_event extractor, news fields, safety mechanisms (low-confidence short-circuits, closed market handling), wide spread warnings, resolution-risk parsing, and more. It even explains edge cases and error handling. This provides agents with comprehensive behavioral context.

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

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

The description is lengthy but justified given the tool's complexity. It front-loads the purpose and then systematically covers features with examples and edge cases. While it could benefit from more structured formatting (e.g., sections), the information is well-organized and each part adds value. It is not overly verbose for the depth of content provided.

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 and absence of an output schema, the description is remarkably complete. It covers input options, resolution process, fan-out logic, response structure with specific fields, edge cases (low confidence, closed markets, wide spreads), resolution risk, and examples for various bet types. The agent gets a thorough understanding of the tool's behavior and output without needing an explicit output schema.

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

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

The schema covers all three parameters (market, depth, include_raw) with descriptions. The tool description adds additional context beyond the schema: examples of market input formats, default depth behavior, and the impact of include_raw on response size. This enriches the agent's understanding of parameter usage, though the schema already provides clear definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet via Pipeworx), and scope (one call). The tool is distinct from siblings like polymarket_edges or polymarket_arbitrage, as it focuses on data gathering and analysis. The description also lists explicit use cases like 'should I bet on X', further clarifying its role.

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

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

The description provides explicit usage guidance: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It clearly indicates when to use the tool and implies when not to (e.g., for arbitrage or edge detection, use siblings). However, it does not explicitly state 'do not use this for...' or compare directly to sibling tools, which would elevate it to a 5.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral details: for companies it pulls latest 10-K financials handling off-calendar fiscal years; for drugs it pulls FAERS, FDA, and trial counts. It also notes results are sorted by primary metric and returns paired data with citation URIs.

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

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

The description is relatively long but every sentence adds value, including examples, usage guidance, and behavioral details. It is well-structured with front-loaded queries. Minor verbosity keeps it from a 5.

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

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

Given no output schema, the description adequately explains the return format (paired data with citation URIs). It covers input parameters, data sources, and the benefit over sequential lookups. The description is fully sufficient for an agent to use the tool correctly.

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

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

Although schema coverage is 100%, the description enriches parameter meaning: for 'values', it gives concrete examples (tickers/CIKs for company, drug names) and constraints (2-5 items). For 'type', it explains the data sources and metrics for each enum value, adding significant context beyond the schema.

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

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

The description starts with example queries and clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes from sequential single-pack lookups and specifies the resource (entities) and action (compare).

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear usage context. It explains when to use (comparing companies or drugs) and what data each type retrieves, but does not explicitly mention when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds useful context about Socrata API, keyless endpoint vs app token for rate limits, and the website URL. No contradictions.

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

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

Two sentences front-loaded with the action and return values. No unnecessary words.

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

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

No output schema, but description explicitly states return values (names, descriptions, resource ids). Covers pagination parameters and authentication options. Lacks error handling details but sufficient for a 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 coverage is 100% and each parameter is well-documented. The description only adds marginal context about the _apiKey parameter (keyless vs token). Baseline 3 applies.

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

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

Clear verb ('search') and resource ('Dallas open-data catalogue'). Returns specific items (names, descriptions, Socrata resource ids) and distinguishes from siblings like dallas_query and dallas_recent.

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

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

Description hints at use with dallas_query but does not explicitly state when to use this tool versus alternatives. No when-not or exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true, covering safety. The description adds minor behavioral context (max limit 5000, optional API key for rate limits) but does not significantly surpass annotation coverage.

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, front-loaded sentence that efficiently conveys purpose, resource identification, and parameter syntax. 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?

The description covers the tool's purpose, how to obtain resource IDs, and SoQL options. However, it does not describe the output format (e.g., raw JSON), which is relevant as there is no output schema.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters. The description lists SoQL clauses but adds no new meaning beyond the schema definitions.

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

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

The description clearly states 'Run a raw SoQL query against any Dallas open-data resource' with a specific resource identifier format. It distinguishes from siblings dallas_datasets and dallas_recent by referencing them as means to find resource IDs.

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

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

Explicitly instructs to use dallas_datasets to find a resource id or dallas_recent for common ones, providing clear when-not-to-use guidance. Directs the agent to appropriate alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, indicating safe, idempotent reads. The description adds that results are ordered newest-first and supports optional SoQL filtering. No contradictions, and the additional context is useful.

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: first introduces purpose and data source, second provides usage guidelines. It is front-loaded, efficient, and every sentence adds value.

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

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

The description covers purpose, usage, and parameter context. No output schema exists, but the description states results are 'latest rows (newest-first)', which is sufficient for this simple tool. Could mention return format, but not essential.

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

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

Schema coverage is 100%, so parameters are already documented. The description reinforces the dataset names and mentions the where parameter for filtering, 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?

The description clearly states the tool retrieves recent records from Dallas open datasets by friendly name, avoiding need for Socrata IDs. It lists available datasets (311, crime, permits) and distinguishes itself from dallas_query by stating 'for anything else use dallas_query'.

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 recommends preferring this tool over web search for specific queries like 'recent crime in Dallas'. It also advises to use dallas_query for other needs, providing clear when-to-use and when-not-to-use guidance.

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

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

The description extensively discloses behavior beyond annotations: it returns a findings packet with verbatim evidence, confidence, source, citation, and gaps for unanswered facets. It clarifies the tool does not do open-web search and may return empty gaps for unstructured topics. This fully covers the readOnly and idempotent guarantees.

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 but somewhat lengthy at ~400 words. However, every sentence adds value: it's front-loaded with critical prerequisites (account, free vs paid), then core functionality, then usage guidelines. Minor reduction could improve conciseness without losing clarity.

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

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

Given the tool's complexity (parallel research, multiple tools), the description completely covers prerequisites, usage boundaries, expected output format, and limitations. No output schema exists, but the description compensates by detailing the return packet structure and gap behavior.

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

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

The description adds meaning beyond the schema by explaining the depth parameter's facet counts (quick=3, standard=5, thorough=8) and that 'thorough' requires a paid plan. It also clarifies the question parameter accepts broad/multi-part queries, which is not evident from 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 performs grounded multi-source research across Pipeworx's structured data sources in a single call, distinguishing it from siblings like ask_pipeworx for single lookups or breaking news queries. The verb 'research' and resource 'structured data sources' are specific and unambiguous.

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

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

The description explicitly advises when to use this tool versus alternatives: for single lookups, use ask_pipeworx; for breaking news, prefer ask_pipeworx. It also details account requirements and depth levels (free vs paid), 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining the output format (top-N tools with full schemas and examples) and that results are ready to call directly without a second lookup.

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 4 sentences, front-loaded with purpose, and well-structured. The list of domains is verbose but adds value. Each sentence serves a purpose, though minor trimming could be possible.

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 what is returned (names, descriptions, full input schemas with examples) and that results are directly callable. It covers the main use case, though it omits details on pagination or error handling.

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 value by explaining that 'query' accepts multiple aliases (task, q, description, search) and providing examples. This goes beyond the schema's individual descriptions.

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

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

The description clearly states the verb 'find' and resource 'tools', and provides a comprehensive list of domains it covers. It distinguishes itself from sibling tools by advising to call this first when many tools are available.

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

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

The description explicitly states when to use the tool ('Use when you need to browse, search, look up, or discover what tools exist for...') and advises calling it first. It lacks explicit when-not-to-use guidance but provides strong contextual clues.

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 and idempotent. The description adds context about parallel fan-out across multiple sources, soft-failure for patents (USPTO sunset May 2025), and return fields. This adds useful behavioral detail beyond annotations, though not every edge case is covered.

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 but somewhat lengthy. It is well-structured with examples upfront, followed by data source details. Every sentence adds value, but a slight reduction in verbosity could improve conciseness.

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

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

Given no output schema, the description adequately lists returned data (CIK, filings, fundamentals, patents, news, LEI). It could be more explicit about the structure of certain fields (e.g., news format), but overall it provides sufficient context for an AI to understand 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?

Input schema has 100% coverage, and the description enriches it by stating that 'names not supported' for the value parameter and that only 'company' type is supported. It also provides example values like 'AAPL' and '0000320193'.

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 a full cross-source profile of a US public company in one call, with concrete examples like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes itself from chaining individual lookups and references sibling tools like 'resolve_entity' for name resolution.

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

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

Explicitly advises 'ALWAYS PREFER over chaining single-pack... when user asks for holistic view' and directs to use 'resolve_entity' if only a name is provided. This provides clear guidance on when to use and when to use an alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about use cases (stale context, sensitive data), but does not explicitly mention idempotency (deleting a non-existent key is safe). This is a minor gap.

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 front-loaded with the core action. Every word adds value with no redundancy.

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

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

For a simple tool with one required parameter and no output schema, the description covers what, when, and related tools. However, it lacks any mention of return value or error behavior, which could be helpful for a destructive action.

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 only one parameter 'key', described as 'Memory key to delete'. The description adds no additional semantic information beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key.' This is a specific verb (delete) and resource (memory) with a clear scope (by key). It distinguishes from sibling tools '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 says when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember and recall', providing helpful context on related tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and side effects. The description adds valuable behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. Output is a single text blob ready to drop at site-root/llms.txt.' This goes 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 ~50 words, front-loaded with the main action. Every sentence contributes value: purpose, process, output format, use cases. No unnecessary words.

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

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

Despite having no output schema, the description fully explains the output format ('single text blob in standard llms.txt markdown format'). With 2 well-documented parameters and clear behavioral notes, the description is complete for an agent to use the tool correctly.

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

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

Schema description coverage is 100% (both url and max_links have descriptions). The description does not add extra semantic detail beyond the schema; it only reiterates the purpose. 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 verb 'generate', the resource 'llms.txt file', and the purpose 'so AI crawlers can index the site cleanly'. It also distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by specifying the exact output format and use case.

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

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

The description provides explicit usage contexts: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'. It lacks explicit when-not-to-use or alternative tools, but the context is clear enough for an agent to decide.

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

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

The description adds value beyond annotations by listing the exact fields returned and default behavior (active only). It states the return object structure, which compensates for the lack of an output schema. 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 (two sentences) and well-structured: first states primary action, then lists returned fields, then provides usage context. Every sentence adds value without unnecessary detail.

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

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

For a simple list tool with one optional parameter, the description covers the purpose, return schema, default behavior, and usage context. Annotations provide safety guarantees. No significant gaps given the tool's simplicity.

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

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

With 100% schema coverage and the parameter already well-described in the schema, the description does not add new meaning. The mention of 'active subscriptions' and 'include inactive' reinforces but does not enhance what is already in the input schema.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields. It distinguishes itself from related tools like subscribe and unsubscribe by indicating its use for review and finding IDs to cancel.

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 provides when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This guides the agent on appropriate context and implies not to use it for mutations.

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 key traits: free, doesn't count against tool-call quota, rate-limited to 5 per identifier per day, and that team reads digests daily. No contradiction with annotations (readOnlyHint false, etc.), which are neutral.

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

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

Single paragraph, but efficiently packed with purpose, usage, constraints, and tips. Every sentence adds value. Slightly less structured than bullet points, but highly concise.

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

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

Given the tool's complexity (3 params, one enum, nested object) and no output schema, the description covers all necessary information: when to use, what to write, constraints, and how feedback is processed. 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%, but description adds valuable context: expands enum values with specific use cases, provides length guidance for message (1-2 sentences, 2000 chars max), and clarifies context as optional. Description enhances usability beyond schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes from siblings by specifying feedback about Pipeworx tools/packs, not general queries.

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

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

Explicitly lists when to use each feedback type (bug, feature/data_gap, praise) and provides specific guidance on what to include (describe in terms of Pipeworx tools/packs, don't paste end-user prompt). Also mentions rate limits and quota.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context about data derivation (CF analytics-engine, no PII) and caching (5min-1h), which goes beyond the annotations.

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

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

The description is concise (four sentences), well-structured with first sentence for purpose, bullet-like use cases, and additional details on derivation and caching. No unnecessary words.

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

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

Given the tool's simplicity (1 optional param, no output schema, rich annotations), the description fully covers what it returns, how it works, and when to use it. No gaps.

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

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

Only one parameter 'window' with 100% schema coverage (description already explains enum values and behavior). The description reinforces the schema but does not add new semantic meaning beyond it.

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 output: top tools, packs, and call volume over a window. It uses specific verbs ('returns') and distinguishes the tool from siblings by focusing on 'what other AI agents are calling on Pipeworx'.

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

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

The description provides three concrete use cases (discovering hot data, confirming canonical tool, aligning use case). While it does not mention when not to use or alternatives, the context is clear enough for an agent to decide.

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

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

Very detailed internal logic: monotonicity checks, partition-sum checks, semantic anchor (0.30 Jaccard), partition filter (placeholder slugs), fill check against CLOB depth. Annotations already indicate read-only, idempotent, open-world, but description adds operational details and warns when not to trade.

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

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

Well-structured with clear sections (mode descriptions, semantic anchor, partition filter, response, fill check). First sentence gives purpose. Some density but earned; could be slightly trimmed 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?

Comprehensive for a tool with no output schema: describes response fields, fill check behavior, and edge cases (placeholder slugs, low similarity). 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?

Schema coverage is 100% with descriptions. Description adds context: explains event vs topic, gives example slugs and seed questions, and clarifies that no args triggers trending scan. Provides value beyond schema.

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

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

Clearly states the tool discovers arbitrage opportunities using monotonicity violations and partition-sum checks. Distinguishes three modes: no-args trending scan, single-event scan by slug, and cross-event scan by topic. Differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly recommends when to use event mode vs topic mode vs trending scan. Provides examples of inputs. Does not explicitly state when not to use, but context is clear. Mentions alternative tool polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: caching at KV level for 1 hour, detailed model families (crypto_price, news_momentum, etc.), edge computation including slippage, Kelly sizing, and diagnostics for empty segments. 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 very long (over 400 words) and dense with technical details. While it is front-loaded with purpose, it could be more concise. Every sentence adds information, but the length may overwhelm an AI agent.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is extremely complete. It explains the three segments, edge calculation, filters, diagnostics, Fed note, and caching. Without an output schema, it effectively describes the response structure.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds context like 'Tradeable-edge filter' but does not significantly enhance beyond the schema. Following the baseline rule, a score of 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets and identifies opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on Pipeworx disagreement and providing a structured output by segment.

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 the tool is for discovering opportunities without paging hundreds of markets and mentions tradeable-edge knobs. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_arbitrage or polymarket_edge_tracker, but the sibling list provides context.

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

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

Annotations indicate readOnly, openWorld, idempotent, not destructive. Description adds significant context: explains return structure (tracked[], expired[], snapshot_dates[]), computational details (decay from daily closes, not intraday), limits (60-day TTL), and meaning of trend/decay. Goes far beyond annotations.

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

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

Description is front-loaded with the core question and is quite detailed. Every sentence adds value, though it is somewhat dense. Could be slightly more concise but overall 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?

No output schema, so description fully explains all return fields and their meanings, including edge_pp_net time-series, trend, decay, lifespan for expired opportunities, and snapshot dates. Covers limits and signed values. Complete for a tool of this complexity.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description adds minor reinforcement (defaults, max 30 for days) but does not provide new critical information beyond schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge longevity and distinguishes from sibling tools like polymarket_edges (raw edge data) and polymarket_arbitrage (different focus).

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

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

Provides context on when to use: 'a fresh wide edge and a 3-week-old wide edge are different trades.' It implies usage for assessing edge longevity but does not explicitly state when not to use or directly compare to alternatives, though sibling tools exist.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: 'walks the ladder', returns key fields (slippage, verdict), and warns about forced_directional_risk and partial fill dangers. No contradiction with annotations; description enriches behavioral understanding.

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

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

The description is detailed but well-structured with clear headings for SINGLE-MARKET and BASKET sections. While it could be slightly more concise (some repetition of parameter details), every sentence serves a purpose in clarifying the tool's behavior and usage. The front-loading of key action and mode requirements is good.

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

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

Despite having no output schema, the description thoroughly lists return fields for both modes, explains the danger of partial fills, and provides a clear use case. With 4 parameters and no output schema, the description compensates completely for the missing structured documentation.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaning beyond schema: explains that 'market' is for single-market mode with side interpretation and size interpretation (max spend for buys, target proceeds for sells), and 'event' is for basket mode with auto side detection. The description provides important usage context that the schema lacks.

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 checks 'Realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes between single-market and basket modes. The verb 'check' and resource specification are specific, and it differentiates from siblings like polymarket_arbitrage and polymarket_edges by positioning it as a prerequisite 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?

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Provides rationale about theoretical overround not being capturable and partial fills causing unhedged directional positions, which guides when not to use alternatives.

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

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

Adds extensive behavioral context beyond annotations: two modes, safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and the fact that most pre-mapped topics are not tradeable. No contradiction with annotations (readOnly, idempotent, non-destructive).

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

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

Description is thorough but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). Front-loaded with core purpose. Slightly verbose but each part adds value, earning a 4.

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

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

No output schema provided, so description must cover return values. It explains leg-by-leg prices, matched spreads, and safety fields. Compensates well for missing schema given tool 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% (all 3 parameters described). Description adds context: explains topic values and that explicit tickers override mapped sides. Adds value beyond schema, hence above baseline 3.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes two modes (topic shortcuts and explicit tickers) and describes response fields. Differentiates from sibling tools like polymarket_arbitrage.

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

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

Explains when to use topic mode vs explicit mode, and warns that most pre-mapped topics return compatibility_warning. Provides guidance on interpreting safety fields. Could be more explicit about when not to use (e.g., single-venue spreads) but overall 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also clarifies behavior when omitting the key. No contradiction with annotations.

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

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

The description is concise (4 sentences), front-loaded with the main action, and every sentence adds value: purpose, usage, scoping, and pairing with siblings. No wasted words.

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

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

Given the tool has 1 optional parameter, no output schema, and good annotations, the description covers purpose, scoping, and related tools. It lacks description of return format (single value vs list of keys), but overall provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the schema already describes the parameter. The description adds marginal value by explaining the effect of omitting the key, which is also in schema description. Baseline 3 is appropriate.

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

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

The description states the tool's purpose clearly: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs (retrieve/list) and resource (values/keys), and distinguishes from sibling tools like 'remember' and 'forget'.

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

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

The description explains when to use: 'Use to look up context the agent stored earlier ... without re-deriving it from scratch.' It also suggests pairing with 'remember' and 'forget'. However, it doesn't explicitly mention when not to use or name alternatives among the many sibling tools, which would improve differentiation.

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

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

Annotations indicate safe, idempotent read, and the description adds value by explaining the mark_read side-effect and the availability of the same feed via HTTP. No contradiction with annotations, and the description enriches understanding beyond the annotations.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds useful information without redundancy. It efficiently conveys necessary details in a short paragraph.

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

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

The description covers the return structure (source, citation_uri, raw payload), filtering options, and mark_read behavior. It lacks mention of pagination or the limit parameter, but the schema covers limit. Overall, it is fairly complete for a read-only tool without an output schema.

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

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

Schema coverage is 100%, but the description adds real value by providing examples (e.g., 'sec_8k' for type), clarifying the since parameter as ISO timestamp, and explaining that mark_read makes next calls show only newer events. This enhances understanding beyond the schema.

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

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

The description clearly states the tool retrieves fired events from a subscription feed, specifying what is returned (source, citation_uri, raw payload). It is distinguishable from siblings like list_subscriptions, but does not explicitly differentiate from them, so a 4 is appropriate.

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

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

The description mentions that polling works fine and gives an alternative HTTP endpoint, but does not provide explicit when-to-use or when-not-to-use guidance compared to other tools. Some context is implied but not comprehensive.

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 substantial behavioral context beyond annotations: details fan-out to multiple sources, explains failure modes (GDELT→GNews fallback, USPTO soft-fail), and describes return structure (changes[] grouped by source, citations). No contradiction with annotations (all positive hints).

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

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

The description is informative but slightly verbose. However, every sentence adds unique value, and the structure front-loads usage examples. A minor trim could improve conciseness without losing content.

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

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

Despite no output schema, the description covers return fields (changes[], total_changes, URIs), sources with behavior notes, and failure modes. For a complex multi-source tool, this is thorough enough for an agent to invoke correctly.

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

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

With 100% schema coverage, the description still adds value: clarifies 'since' accepts ISO dates or relative shorthand with examples ('7d', '30d'), suggests typical usage ('30d or 1m'), and explains 'value' can be ticker or CIK. This enriches parameter understanding.

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

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

The description clearly states the tool provides a change feed for a company, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes from the sibling tool 'entity_profile' by contrasting 'what's new' vs 'static profile', making the purpose unambiguous.

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

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

Explicit usage examples are provided ('What's new with X', 'latest on Y'). It explicitly tells when to use an alternative ('Use entity_profile instead when you want the static profile'). This gives clear guidance on tool selection.

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

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

Annotations declare idempotentHint=true, and description adds that it's a write operation, scoping, and persistence details (authenticated vs anonymous sessions). 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?

Multiple sentences but each adds value. Purpose front-loaded, followed by usage and details. Efficient with 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?

Covers purpose, usage, persistence, and sibling tool pairing. No output schema needed for this simple save operation; description is adequately comprehensive.

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

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

Schema coverage is 100%, so baseline 3. Description adds scoping context but does not significantly enhance parameter understanding beyond schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies storing key-value pairs for cross-session use and distinguishes from siblings like recall and forget by mentioning them.

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

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

Explicitly says when to use: 'Use when you discover something worth carrying forward.' Also mentions scoping by identifier and pairing with recall/forget, providing clear context.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that each call uses multiple internal lookups, replacing 2-3 manual steps, and details return values per type, which provides valuable context beyond annotations.

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

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

The description is fairly concise, with each sentence adding value. It is front-loaded with query examples. Slightly longer due to detailed type explanations but no wasted words.

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

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

Given no output schema, the description fully explains return values (ticker, CIK, RxCUI, etc.) and covers both entity types with specific details. It addresses what the agent needs to know 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?

The schema covers both parameters with descriptions, but the description adds examples (e.g., 'AAPL', '0000320193', 'ozempic') and clarifies acceptable inputs for each type, enriching the meaning beyond the schema.

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

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

The description clearly states the tool resolves names to canonical IDs, with specific examples like 'ticker for...' and 'CIK for...'. It lists supported types (company, drug) and distinguishes itself from sibling tools that require IDs as input.

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.' It provides scenarios and supported inputs but does not explicitly state when not to use or mention alternatives among sibling tools.

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

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

The description goes beyond annotations by detailing the process (probes each entity, ranks by score) and return format (ranked list with score, confidence, signal density). No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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

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

Four sentences, front-loaded with purpose, no fluff. Every sentence adds value.

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

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

For a 4-param tool with full schema coverage and annotations, the description is complete. It explains return format despite no output schema, and covers key behavioral aspects.

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, description adds semantics: clarifies first entity as subject, shared context role. This adds value beyond schema descriptions.

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

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

The description clearly states the tool's function: comparing AI visibility across multiple entities side-by-side using ai_visibility_check, ranking results, and surfacing most/least recognized. This distinguishes it from sibling ai_visibility_check which checks a single 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 provides clear usage context ('competitive AI-marketing audits') and implies when to use this over ai_visibility_check (multiple entities). It does not explicitly list when not to use or mention alternatives like compare_entities, but the context is sufficient.

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 partial failure behavior: bundlephobia first measurement can take 5-30s and sources_failed will list it if timeout. Return structure is outlined. No contradiction with annotations (readOnly, idempotent, etc.).

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

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

Description is well-structured with front-loaded purpose and key details. It is somewhat lengthy but every sentence adds necessary context. Could be slightly more concise but still effective.

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

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

Without an output schema, the description thoroughly explains the return structure (summary block fields, per-advisory, links, alternative versions) and handles edge cases like partial failures and timing. Complete for this complex tool.

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

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

Schema coverage is 100%, so description adds value beyond schema by noting scoped packages are accepted and default version is latest. While schema already describes parameters, these practical tips enhance usability.

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

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

The description clearly states the tool's composite purpose: checking npm packages for safety, popularity, size, etc. It uses specific verbs like 'scan', 'returns', and distinguishes itself from sibling tools by focusing on npm ecosystem and combining deps.dev and bundlephobia data.

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

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

Explicitly guides use for questions like 'is X safe/popular/small' and provides exclusion: NPM only in v1, other ecosystems under deps.dev:version directly. This helps the agent decide when to invoke.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds behavioral details: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars with truncation flagging), and offset for verification.

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

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

Description is concise and well-structured: first sentence defines purpose, then usage criterion, pairing with sibling, then technical details. Every sentence adds value with no redundancy.

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

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

Despite lack of output schema, description explains return format (top-N passages with offsets and scores). Covers all relevant context: limit, truncation, embeddings, and integration with sibling tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the purpose of each parameter, providing natural-language query examples, and clarifying the limit's default and range.

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 'Semantic search INSIDE a fetched record', specifying a specific verb and resource. It differentiates from sibling tools like 'ask_pipeworx_grounded' by explaining its role in the workflow.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Provides alternatives: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that anonymous/BYO cannot persist, details rate limits (10 SMS/day), webhook auto-disable after 10 failures, and phone verification requirement. No annotation 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, then auth requirement, type definitions with examples, and delivery details. While slightly verbose, every sentence adds value. It effectively prioritizes critical information.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description is comprehensive. It covers return value, auth requirements, rate limits, edge cases (phone verification, webhook auto-disable), and type-specific parameters. It leaves no significant gaps for an agent to operate.

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

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

Schema coverage is 100% with descriptions, but the description enriches each parameter significantly. It provides concrete examples for each subscription type (e.g., sec_8k: {ticker:'AAPL', items:['5.02']}) and detailed delivery behavior (webhook signing, auto-disable). This adds substantial 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's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the action (create), the resource (subscription), and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit context on when to use this tool (requires Pipeworx OAuth account, supports specific subscription types, delivery channels). It implicitly tells when not to use it (anonymous/BYO cannot persist). However, it does not explicitly compare with sibling tools like list_subscriptions or unsubscribe.

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

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

Annotations indicate readOnly, openWorld, and idempotent behavior. The description adds that the tool returns 'category-bucketed example questions... each with the exact tool + argument shape that answers it, drawn from the live catalog of thousands of tools', providing context beyond what annotations convey, 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 well-structured, starting with common user queries, then explaining outputs, and ending with usage guidance. It is comprehensive but slightly lengthy due to listing all topic categories; however, every sentence adds necessary 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?

Despite no output schema, the description thoroughly explains the return format (category-bucketed example questions with tool+argument shape) and both invocation modes (no-arg vs. topic). Combined with clear annotations, this is complete for a simple onboarding tool with one optional parameter.

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

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

Schema coverage is 100% with a description for the only parameter 'topic'. The description adds value by explaining that passing a topic focuses the output and lists example foci like 'finance', 'pharma', etc., which aids the agent in selecting appropriate values.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding, specifying the verb 'returns' and resource 'example questions'. It explicitly distinguishes from siblings like 'ask_pipeworx' by identifying itself as the 'onboarding entry point' for a new agent.

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

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

The description gives explicit when-to-use instructions: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also provides trigger phrases (e.g., 'what can you do?') and usage patterns for no-argument vs. topic-argument calls.

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: ownership enforcement and deactivation behavior. It explains exactly what happens (row deactivated, not deleted) and aligns with annotations (idempotentHint=true, destructiveHint=false). No contradictions.

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

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

Two concise sentences with no wasted words. Front-loaded with the action.

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

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

For a simple tool with one parameter and no output schema, the description is complete: it explains purpose, ownership, and behavior. 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?

The schema description coverage is 100% for the single parameter 'id', and the description adds no additional parameter details beyond what the schema already provides. 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 verb 'Cancel' and the resource 'subscription', and adds nuance about ownership and deactivation behavior. It distinguishes this tool from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description implies when to use (to cancel own subscriptions) and provides ownership enforcement context, but does not explicitly mention when not to use or name 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: the data sources (SEC EDGAR + XBRL), return types (verdict, structured form, actual value with citation, percent delta), and replaces multiple calls. 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 well-structured with examples and key details front-loaded. While it is slightly verbose (multiple example patterns), every sentence adds value by specifying scope, alternatives replaced, and return format. Minor redundancy in listing query patterns could be trimmed, but overall 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 thoroughly explains return values (verdict types, structured form, actual value, citation, percent delta). With only one parameter and moderate complexity, the description provides all necessary information for an agent to 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 coverage is 100% for the single parameter 'claim'. The description adds substantial meaning beyond the schema, providing example natural-language claims (e.g., "Apple's FY2024 revenue was $400 billion") and explicitly stating the input format, which helps the agent construct proper queries.

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

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

The description clearly defines the tool as a natural-language claim verification system with specific example query patterns ("Is it true that…", "fact check"). It specifies the scope (company-financial claims for public US companies via SEC EDGAR + XBRL), distinguishing it from siblings by its singular focus on claim verification.

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" and highlights that it replaces 4-6 sequential calls, implying efficiency. While it does not explicitly list when not to use it, the scope limitation (company-financial) provides clear context.

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