Foursquare

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 value by disclosing behavioral details: it probes multiple models, requires a BYO key for Anthropic (with cost implication), and returns per-model fields (score, confidence, signals, raw_response). 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 two sentences, front-loaded with the core action and score metric, and efficiently covers purpose, parameters, use cases, and return format without fluff. Every sentence earns its place.

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

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

Given the tool's complexity (4 params, no output schema but rich annotations), the description is comprehensive. It explains return format (per-model combined view) and use cases. Minor gap: does not detail scoring algorithm, but that may be internal. Overall, it is well above minimum viability.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema: it explains default model behavior, the necessity of _apiKey for Anthropic probing, and gives example entities for context. This enriches the agent's understanding of parameter usage.

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

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

The description clearly states the tool probes LLMs for what they know about an entity and returns a visibility score (0-100) per model. It specifies the default model (Workers AI Llama-3.3-70b) and distinguishes from sibling tools like scan_competitor_ai_presence or ask_pipeworx by focusing on AI visibility measurement rather than direct Q&A or competitor scanning.

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

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

The description explicitly mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. While it does not state when not to use or list alternatives, the context is clear and the intended scenarios are well-defined, providing adequate guidance for the agent.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context about routing to 4,774 tools and returning structured answers with citation URIs, which goes beyond annotations without contradicting them.

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

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

Front-loaded with the key instruction 'PREFER OVER WEB SEARCH'. Well-structured with clear sections: when to use, what it does, examples, and alternatives. Every sentence contributes meaning.

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

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

Given the tool's complexity as a meta-query router, the description covers its purpose, usage scope, examples, and fallback tools. It sufficiently informs the agent of the tool's capabilities and limitations without needing output schema details.

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

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

Schema coverage is 100% with all parameters described as aliases. The description provides numerous concrete examples and clarifies the domain (natural language factual questions), adding value beyond the schema definition.

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 routes factual questions to a vast set of verified sources and returns structured answers with citations. It lists many specific domains and explicitly contrasts with siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicit guidance to prefer over web search for factual questions about real-world entities. Provides when-to-use and when-to-step-up conditions, including specific tool alternatives for different needs (hallucination-resistant, broad multi-part) and mentions breaking news handling.

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. Description adds critical behavioral traits: hallucination-resistant, uses only tool result, returns explicit refusal reasons (e.g., not_in_source, tool_error), and mentions extra LLM call cost. 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?

Description is front-loaded with purpose and mechanism, then return format and usage guidance. Every sentence adds value, but length is justified for a high-stakes tool. Slightly verbose but 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?

Given the complexity (routing among 4,774 tools, 1242 sources, extra LLM call), the description fully explains behavior, return structure (success and refusal), refusal reasons, and cost trade-off. No output schema, so description carries burden and does so completely.

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

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

Schema coverage is 100% with descriptions for all 6 parameters (aliases for question). Description does not add meaningful detail beyond the schema; it says 'Your question in natural language' which is already implicit. Baseline 3 is appropriate as schema handles parameters adequately.

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

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

Clearly states 'Hallucination-resistant answer mode for high-stakes reads' and details extraction using only tool result, returning answer with evidence. Distinguishes from sibling ask_pipeworx by noting extra cost and causal vs. high-stakes use.

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

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

Explicitly specifies when to use: 'whenever an answer will be quoted, cited, or acted on' in high-stakes domains. Also provides when-not: 'prefer ask_pipeworx for casual lookups', with reasoning about extra LLM call cost.

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. Description adds extensive behavioral details: fan-out patterns, resolver confidence, parent event extraction, news fallback, safety short-circuits, resolution rule risk. 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?

Very detailed and well-structured with labeled sections. Slightly verbose but justified by tool complexity. Front-loaded with purpose and usage.

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

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

Covers all major aspects: inputs, outputs, safety, edge cases, resolution, news behavior. No output schema, but response shapes are thoroughly documented.

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

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

All three parameters are described with additional context beyond schema: market input formats, depth default and behavior, include_raw size implications. Schema coverage is 100%, and description enriches meaning.

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

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

Clear verb (research) and resource (Polymarket bet via Pipeworx data). Distinguishes from sibling tools like polymarket_edges by focusing on a single bet's data packet. Examples of inputs and outputs solidify purpose.

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

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

Explicitly states use cases ('should I bet on X', 'what does the data say about Y'). Provides guidance on when to inspect resolver contract. Does not explicitly mention when not to use or compare to siblings, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing how fiscal years are handled (off-calendar correctly), sorting by primary metric, and including citation URIs. No contradiction with annotations.

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

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

The description is dense but well-organized with example queries and a clear separation of concerns. It could be slightly more concise by removing some redundancy, but front-loads the essential purpose and usage guidance effectively.

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

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

Given the tool's complexity (2 required params, no output schema) and the richness of annotations, the description fully covers purpose, usage, behavioral details, and parameter semantics. No gaps remain for an agent to understand invocation.

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

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

Schema coverage is 100% and the description significantly enriches parameter meaning. It explains that 'type' determines data source (SEC vs FAERS) and that 'values' require tickers/CIKs for companies and drug names for drugs, with examples and constraints.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, specifying data sources (SEC EDGAR for companies, FAERS for drugs) and metrics. It distinguishes itself from sequential single-pack lookups, making its purpose unequivocal.

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 instructs to prefer this tool over sequential lookups when comparing entities. It provides example query phrases ('Compare X and Y', 'which is bigger') and explains data retrieval behavior, offering clear when-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?

Adds significant behavioral context beyond annotations: decomposes questions, routes to 4,774 tools in parallel, returns findings packet with evidence/confidence/source/fetched_at/citation and explicit gaps[]. Warns about 15-60s response time and that breaking news returns empty gaps. 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?

Description is long but front-loaded with account requirement, core capability, examples, alternatives, and edge cases. Every sentence adds value, though slightly verbose; could be trimmed slightly 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?

For 2 parameters with 100% schema coverage and no output schema, the description is very complete: explains input semantics, output format, behavior, alternatives, and edge cases (gaps[], breaking news). Warns about response time.

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 nuance: depth enum explained (quick=3, standard=5, thorough=8) and notes that question is natural language broad/multi-part, adding value beyond schema.

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

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

The description clearly states it is for 'grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources' and distinguishes it from open-web search. It gives specific examples like 'compare X and Y's regulatory + financial exposure', and differentiates from sibling tool ask_pipeworx.

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

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

Explicitly tells when to use (broad/multi-part questions over structured data) and when not to (breaking news, single lookup). References sibling tools (ask_pipeworx) and notes account requirements and plan limitations.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral detail beyond annotations: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the rich return format and that it is a non-destructive, idempotent 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 concise and well-structured: front-loaded with the primary action, then usage context, then return format. No superfluous sentences; every sentence adds value.

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

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

Given the tool's complexity as a meta-tool with multiple parameters and no output schema, the description adequately covers behavior, return format, and usage context. It explains that results include schemas ready to use, which is critical for an AI agent to act on the output.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions aliases and gives examples for the query parameter, but does not add significant semantic meaning beyond what the schema already provides. The description reinforces but does not expand on parameter usage.

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

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

The description clearly states the tool discovers tools by describing data or task. It distinguishes from siblings by positioning itself as the first call for browsing options, and lists specific domains. The verb+resource 'find/discover tools' is explicit 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?

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available.' This provides clear context and suggests it's a meta-tool for discovery before invoking other 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, etc. The description adds valuable behavioral context: that it fans out across multiple sources, returns specific data fields, includes URIs for filings, and notes the patent soft-fail. However, it does not discuss error handling or rate limits, so it's not a perfect 5.

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

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

The description is front-loaded with examples and a clear purpose, but it is a single dense paragraph. It is appropriately sized given the tool's complexity, though better structuring (e.g., bullet points for outputs) could improve readability.

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

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

Given the tool's complexity (multi-source aggregation) and the absence of an output schema, the description does a thorough job of specifying inputs, outputs, limitations, and fallbacks. It covers most aspects an agent needs to understand the tool's capabilities 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 both parameters are described. The description adds meaning beyond the schema by clarifying that value can be ticker or zero-padded CIK, and that type currently only supports 'company' with future plans. This extra context justifies a score above the baseline 3.

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

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

The description begins with many example queries, clearly states the verb 'profile' and resource 'US public company', and distinguishes itself from siblings like resolve_entity by explicitly stating that names are not supported. It also lists the sources and outputs, making the purpose unmistakable.

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

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

The description explicitly tells the agent to 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view.' It also instructs to use resolve_entity if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false; description adds context about clearing sensitive data but doesn't provide additional behavioral details beyond annotations.

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

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

Two sentences, no fluff, efficient communication of purpose and usage.

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 single parameter, no output schema, and annotations present, the description fully covers what the tool does and when to use it.

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

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

Schema has 100% coverage with clear description for the only parameter 'key'; description does not add extra meaning beyond 'Memory key to delete'.

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 'Delete a previously stored memory by key', specifying verb and resource. Distinguishes from siblings remember and recall by mentioning pairing.

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

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

Provides explicit when-to-use: stale context, task done, clear sensitive data. Recommends pairing with remember and recall.

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, openWorldHint, and idempotentHint. The description adds that it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' which is consistent and provides additional behavioral context without contradiction.

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

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

The description is concise with three sentences that front-load the core purpose and follow with output format and use cases. Every sentence adds value without redundancy.

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

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

The tool is simple with no output schema, but the description explains the output format ('a single text blob ready to drop at site-root/llms.txt'). Given the annotations and parameter schema, the description is complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for both parameters 'url' and 'max_links'. The description does not add new meaning beyond what the schema provides, 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 the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. The verb 'generate' and resource 'llms.txt file' are specific, and the context of AI crawlers distinguishes it from sibling tools like 'scan_competitor_ai_presence'.

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

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

The description provides explicit use cases: '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 alternatives, but the use cases are clear and 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?

Annotations already provide readOnly, idempotent, and non-destructive hints. Description adds return fields but no additional behavioral traits 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?

Single sentence front-loaded with purpose, followed by field list. No extraneous information.

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

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

For a simple one-param tool with output schema, description covers what it does and what it returns sufficiently.

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

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

Schema has 100% coverage; description reinforces parameter purpose but adds marginal value.

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

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

Clearly states 'Full place details by fsq_place_id' and lists specific fields returned. Distinguishes from sibling tools like search_places and nearby_places.

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

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

Implies usage after obtaining an ID from search_places via param description. No explicit exclusions or alternatives, but context is clear.

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

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

Annotations already convey read-only, idempotent, non-destructive behavior. The description adds context about scope (caller's subscriptions) and return fields, which is useful 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?

Two sentences: first states action and result, second gives usage guidance. No unnecessary words, front-loaded with key information.

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

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

Covers primary use, return fields, and parameter. Lacks details on pagination or ordering but is adequate for a simple list tool with 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 coverage is 100% with a clear description. The description reinforces the default behavior (active subscriptions) but adds no extra semantic detail 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 explicitly states the tool lists the caller's active subscriptions and enumerates return fields. It clearly distinguishes from sibling tools like subscribe and unsubscribe by focusing on reading existing 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 advises using the tool to review subscriptions before adding more or to find an ID to cancel, providing clear use cases. It implicitly contrasts with subscribe and unsubscribe, though explicit exclusions are absent.

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, etc. The description adds value by listing the output fields (name, categories, address, etc.) but does not disclose additional behavioral traits like rate limits or data freshness. With rich annotations, the description's contribution is marginal, hence a score of 3.

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, front-loaded with the core purpose, and every phrase conveys essential information without redundancy. It efficiently covers the main functionality and optional filters.

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 (5 parameters, 2 required), the description covers all key aspects: no text query, required coordinates, optional filters, and returned fields. With an output schema present, details on return values are unnecessary, making this description complete.

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

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

The input schema has 100% coverage with descriptions for all 5 parameters. The description adds extra meaning by clarifying that 'categories' must be numeric fsq_category_ids from a prior result and that radius_m defaults to 500m, which is not fully captured in the schema.

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

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

The description clearly states 'Return POIs sorted by distance from a lat/lon without a text query.' It specifies the verb ('Return'), resource ('POIs'), and a key distinguishing feature (no text query), effectively differentiating it from sibling tools like search_places.

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

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

The description explicitly lists required parameters (latitude, longitude) and optional ones (radius_m, categories) with defaults, providing clear context for when to use this tool. However, it does not explicitly state when not to use it or mention 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 are all false, so the description carries the full burden. It discloses behavioral traits: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' and 'The team reads digests daily and signal directly affects roadmap.' These go beyond what annotations provide, ensuring the agent understands constraints and impacts.

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 but well-structured: purpose, use cases, instructions, behavioral notes. It is concise (no fluff) and every sentence adds value. Ideal length for quick comprehension.

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 3 parameters, 2 required, nested objects, and no output schema, the description is complete. It explains when to use, how to provide feedback, and what happens after submission (team reads daily). No major gaps; the agent can confidently use this tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by instructing 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which guides usage of the `message` parameter. This extra context justifies a 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and distinguishes it from sibling tools which are query/research oriented. This is a clear and unique value proposition.

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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides guidance on what to avoid ('don't paste the end-user's prompt') and mentions rate limits and quota, giving clear usage boundaries.

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. Description adds valuable context: self-aggregating, no PII, caching behavior (5min-1h).

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 core purpose, no fluff. Efficiently conveys all necessary information.

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

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

Given one optional param, no output schema, and annotations covering safety, the description covers behavior, use cases, and caching thoroughly.

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% with enum and description. Description adds nuance on window choice (shorter for hot, longer for steady-state), 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 returns top tools, packs, and call volume over a window, distinguishing it from siblings like discover_tools or ask_pipeworx.

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

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

Explicitly lists three use cases and explains window trade-offs. Lacks when-not-to-use or direct sibling comparisons, but context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. The description adds extensive behavioral context: the fill check (realizable_edge_pp ≤ 0 means do not trade), semantic anchor (Jaccard similarity), and partition filter (placeholder slugs). 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 clear sections for each mode, but it is somewhat verbose with technical details like 'partition_sum check', 'Jaccard similarity', and 'partition filter'. It could be trimmed slightly while retaining essential information.

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

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

Given the tool's complexity and lack of output schema, the description covers all necessary aspects: modes, parameters, response structure (opportunities[], partition_check, fill check), edge cases (placeholders filtered, low similarity), and references a sibling for custom sizing. It is fully self-contained.

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

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

Schema coverage is 100% (both event and topic described). The description adds value by explaining the modes, providing examples of slugs and seed questions, and noting that full URLs are accepted for event. This goes beyond the schema's bare 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks, and breaks down the three invocation modes (no args, event, topic) with specific purposes. It distinguishes itself from sibling tools like polymarket_edges or polymarket_fill_risk by detailing the unique methodology and modes.

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

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

The description provides explicit guidance: when to use each mode (no args for trending, event for specific market, topic for cross-event scanning), explains the semantic anchor and partition filter, and even includes a fill check to determine tradability. It also directs users to polymarket_fill_risk for custom sizing, offering 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?

Discloses detailed behavioral traits including caching (1h at KV level), model families, response segments, and diagnostics. No contradiction with annotations which declare readOnlyHint, openWorldHint, idempotentHint, and 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?

The description is comprehensive but verbose; it is well-structured with segments and diagnostics but could be more concise while retaining key information.

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

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

Given the tool's complexity and lack of output schema, the description fully explains response structure, caching, and how to interpret results, making it complete for agent use.

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

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

Schema description coverage is 100%; the description adds some context but does not significantly enhance parameter meaning beyond what the schema already provides.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific verb and resource. It distinguishes from siblings like polymarket_arbitrage by detailing its unique model-driven segments.

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 sets context as 'what should I bet on today' and explains when to use filter knobs, but lacks explicit guidance on when not to use or direct comparisons to sibling tools.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral details: the response structure (tracked, expired, snapshot_dates), limits (60-day TTL, from when snapshotting enabled), and that decay numbers come from daily closes, not intraday. 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 and front-loaded with the purpose, then args, response details, and limits. Each sentence adds value, though the response format section is somewhat lengthy but necessary given no output schema. Could be slightly more concise but overall efficient.

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

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

Given the tool's 2 optional parameters and complex output without an output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limitations. It covers purpose, usage, behavior, and output details comprehensively.

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

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

Schema coverage is 100%, with both parameters described in the input schema. The description repeats the defaults and briefly mentions the parameters but adds no new meaning beyond what the schema 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 tool's purpose: edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and if it's shrinking. It uses specific verbs like 'track' and 'compute' and distinguishes itself from siblings like polymarket_edges by focusing on time-series analysis.

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 context for when to use the tool (checking edge persistence and decay) and contrasts fresh vs aged edges. It does not explicitly name alternatives or specify when not to use it, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral specifics: walking the order-book ladder, returning a verdict ('clean|degraded|cannot_fill'), and warning about forced directional risk in basket mode. This supplements the annotation safety profile with operational nuance.

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 packs purpose, modes, parameters, outputs, and usage guidance into a cohesive flow. It uses CAPS for mode keywords and bold warnings, improving scannability. While every sentence adds value, a slight reduction in wordiness (e.g., combining some output field lists) could improve conciseness.

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

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

Despite lacking an output schema, the description enumerates all return fields for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs[], max_clean_notional_usd, forced_directional_risk for basket. It also covers edge cases like partial fills and directional risk.

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

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

Schema coverage is 100%, but the description adds contextual meaning beyond field names: explains how `size_usd` interpretation differs between single-market (spend/target proceeds) and basket (settlement notional), clarifies side defaults for basket mode (auto based on partition sum), and provides default values and range clamps.

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 opens with a crisp verb-object statement ('Realizable-vs-theoretical edge check') that immediately distinguishes the tool from siblings like polymarket_arbitrage or polymarket_edges. It then splits into two clear operating modes (single-market and basket) with specific inputs and outputs, removing any ambiguity about what the tool does.

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

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

Explicit 'USE THIS before acting on...' directive ties the tool to concrete upstream actions (arbitrage signals, edge trades above $500). It explains when NOT to skip it by detailing real-world failure modes (theoretical overround not capturable, partial fill → directional risk). This is rare and highly 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses extensive behavioral details: two operational modes, response structure (leg-by-leg prices, spreads in percentage points), safety fields (compatibility_warning, temporal_alignment), and counters for skipped comparisons (skipped_cross_type, skipped_cross_subtype). It also explicitly states that most pre-mapped topics are not tradeable, managing expectations. 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 well-structured: it opens with the core purpose, then details modes, response format, safety fields, and a final caution. Key terms are bolded for emphasis, and every sentence provides useful information. While it could be slightly more concise, the structure is clear and front-loaded.

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

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

Given the complexity of two-venue comparison with multiple safety checks, the description fully explains the tool's behavior, including edge cases (non-equivalent bet shapes, temporal mismatches, semantic mismatches). There is no output schema, but the description compensates by detailing the response fields (prices, spreads, compatibility_warning, temporal_alignment, counters). The agent has all necessary information 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?

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds value by explaining the auto-fetch behavior for topic shortcuts and how explicit parameters override the mapped side. It also provides the full list of topic shortcuts, which is not in the schema's enum but is described. This enriches the agent's 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 it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself by specifying that the tool evaluates bet-shape equivalence and can indicate when signals are meaningful, differentiating it from sibling tools like polymarket_arbitrage. The verb 'spread' with specific venues and 'resolving question' provides a specific, actionable purpose.

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

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

The description explains two usage modes (topic shortcuts and explicit tickers) and when to expect compatibility warnings, including edge cases like unmatched bet shapes or temporal misalignment. It warns that most pre-mapped topics return warnings, guiding the agent to manage expectations. However, it does not explicitly compare with polymarket_arbitrage, leaving some ambiguity about when one should choose this tool over that sibling.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: scope based on identifier (anonymous IP, BYO key hash, account ID) and pairing with remember/forget. This goes beyond the annotations and provides useful transparency.

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

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

The description is three sentences, all essential. The first sentence immediately states the action and key behavior (omit key lists all). It is front-loaded and concise 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?

The tool has one optional parameter and no output schema. The description explains the input behavior but does not describe the return format or structure. For a simple retrieval tool, this is adequate but leaves some ambiguity about what is returned (e.g., format of listed keys).

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

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

The input schema has 100% coverage with a clear description for the 'key' parameter: 'Memory key to retrieve (omit to list all keys)'. The description restates this but does not add new semantic meaning beyond what the schema provides. Baseline is 3.

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

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

The description clearly states the verb 'Retrieve' and the resource 'a value previously saved via remember, or list all saved keys (omit the key argument)'. It differentiates from siblings by naming the associated tools remember and forget, making the tool's purpose highly specific and unambiguous.

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

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

The description provides explicit usage scenarios: 'look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch'. It also mentions pairing with remember and forget, giving guidance on when to use this tool. However, it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Annotations declare readOnlyHint, idempotentHint, etc. The description adds behavioral details: returns alerts from a persisted feed, includes specific fields, filtering options, and the mark_read flag behavior (marks events as read so next call shows newer ones). No contradictions with annotations.

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

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

Three sentences with clear purpose, actionable details, and an alternative endpoint. Front-loaded and every sentence adds value, no wasted words.

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

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

No output schema, but the description explains the returned fields (source, citation_uri, raw payload) and covers filtering, mark_read, and the alternative API endpoint. Complete for a read-only list tool.

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

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

Schema coverage is 100% with good descriptions. The description adds an example type filter ("sec_8k") and clarifies the effect of mark_read, providing slight added meaning beyond the schema. Baseline 3 with positive adjustment.

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 pulls fired events (alerts) from a subscription feed and specifies the fields each alert carries (source, citation_uri, raw payload). It is distinct from sibling tools like list_subscriptions which list subscriptions, not events.

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

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

The description mentions polling works fine and provides an alternative API endpoint for scripts/dashboards, giving context on when to use this tool versus the API. However, it does not explicitly exclude its use in other scenarios or compare against sibling tools, which are quite different.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details like data sources, fallback logic, and PatentsView soft-failure, but does not elaborate on rate limits or error handling beyond the fallback.

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

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

The description is dense and well-structured with examples and explicit differentiation, but is somewhat long. Every sentence adds value, though slight restructuring could improve readability.

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

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

Despite having no output schema, the description explains the output format (changes[] grouped by source + total_changes + citation URIs). For a complex multi-source tool, this is fairly complete, though it could specify more on error states.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining 'since' accepts ISO date or relative shorthand with examples, and that 'value' can be ticker or CIK, which goes beyond the 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 returns a change feed for a company (SEC filings, news, patents) within a time window, with specific query examples. It explicitly distinguishes from sibling tool 'entity_profile', stating when to use that instead.

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 context with example queries ('What's new with X', 'latest on Y'), and clearly advises to use 'entity_profile' for static profiles. It also explains fallback behavior between GDELT and GNews.

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

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

Adds value beyond annotations: describes key-value scoping, persistent vs. anonymous session memory duration. No contradiction with annotations (readOnlyHint=false, idempotentHint=true are consistent).

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?

Every sentence adds necessary information. Front-loaded with purpose, then usage, behavior, and pairing. No redundancy or fluff.

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

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

Complete for a simple key-value storage tool. Covers purpose, usage, conditions, and lifecycle without needing 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 has 100% coverage with descriptive parameter descriptions. Description adds the scope context ('scoped by your identifier') but does not significantly extend 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 saves data for reuse across conversations and sessions. It uses specific verb-resource ('Save data') and distinguishes from siblings by mentioning 'recall' and 'forget' as paired tools.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward' and provides alternatives (recall, forget) for retrieval and deletion.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context: cascades through several lookup endpoints, details return values (ticker, CIK, company name, citation URI; RxCUI, ingredient, brand, citation). Does not address potential failures or data freshness; openWorldHint not explained. Still adds value beyond annotations.

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

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

Description is comprehensive but lengthy (three paragraphs). Front-loaded with example queries, which is good. Every sentence adds value, but could be slightly more concise. No redundancy, but not perfectly lean.

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 fully explains return values for each entity type, including citation URIs. Explains cascading lookups and auto-disambiguation. Given annotations cover behavioral traits, description is complete for an agent to understand tool's functionality and output.

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

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

Schema coverage 100% with descriptions. Description adds value by providing examples and auto-disambiguation info for company, and clarifying accepted formats. However, baseline 3 is appropriate as schema already covers the core semantics.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers required by other tools, with specific example queries. It lists supported entity types (company, drug) with detailed return values, and explicitly distinguishes itself by saying 'use FIRST' when needing an ID, differentiating from siblings like compare_entities.

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

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

Explicitly says 'use FIRST whenever you have a name but need an ID,' providing clear context for when to invoke. Lists accepted input formats for each type (ticker, CIK, name for company; brand or generic name for drug). Notes that it replaces 2-3 manual lookups, implying efficiency.

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

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

Describes the internal mechanism: probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. All annotations (readOnlyHint, etc.) are consistent; no contradictions.

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

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

Four sentences covering purpose, mechanism, use case, and output. Front-loaded with core action, no unnecessary words, each sentence earns its place.

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

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

Covers purpose, process, output format, and use case. No output schema, but description adequately describes return values. Could mention constraints like entity count range (2-8) but that is in 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% (all parameters have descriptions). The description adds value by clarifying that first entity is treated as 'subject' and context disambiguates common names. This goes beyond the schema.

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

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

The description clearly states the verb 'compare' and resource 'AI visibility across multiple entities'. It distinguishes from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (generic comparison) by specifying it probes AI visibility side-by-side.

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

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

Provides explicit context ('competitive AI-marketing audits') with a concrete example query. Does not explicitly state when not to use or list alternatives, but the purpose implies when to use over single-entity tools.

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

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

Adds context beyond annotations: details partial failures degradation, sources_failed list, bundlephobia measurement delay (5-30s), NPM-only scope in v1. Annotations already declare readOnlyHint, idempotentHint, destructiveHint, but description enriches.

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, front-loaded with purpose, every sentence adds value, no filler. Appropriate length for the complex composite tool.

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

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

For a composite tool with no output schema, description lists all return fields, explains ecosystem scope, partial failure, and gives enough context for an agent to understand what to expect.

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

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

Schema coverage 100%, but description adds meaning: scoped packages accepted, version defaults to latest, and lists return fields (summary block, per-advisory, links, alternatives) even without output schema.

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

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

The description clearly states it's a composite check for adding an npm package, fanning out to deps.dev and bundlephobia, and specifies use cases like safety, popularity, size. It distinguishes itself from sibling tools by its specific scope.

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

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

Explicitly says when to use (when asking about safety/popularity/size/cost) and when not (other ecosystems, directing to deps.dev:version directly). Also mentions partial failure behavior.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read operation. Description adds that it returns specific fields but does not disclose any additional behavioral traits like rate limits or authentication needs. No contradiction with annotations.

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

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

Three sentences with no wasted words. Front-loaded with the core purpose, followed by parameter usage and return fields. Extremely 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?

Covers the essential usage pattern and return fields. With an output schema present, the description does not need to detail return values further. Slight gap in explaining the categories parameter format, but schema handles that.

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 fully documented. Description adds value by explaining the relationship between query and location anchor (near or lat/lon) and lists return fields, providing 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?

Description clearly states 'Search Foursquare places' with a specific verb and resource. It distinguishes from sibling tools like 'nearby_places' by mentioning the need to combine a query with a location anchor (near or lat/lon).

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

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

Provides explicit guidance on when to use the tool: combine query with location anchor. Specifies two location options (near or lat/lon). Does not explicitly mention when not to use or alternatives, but the usage pattern is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by disclosing the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character limit (200K chars with truncation flagging), and return structure (passages with offsets and scores).

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 with two paragraphs, front-loaded with purpose. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains return values (passages with offsets and scores). It covers limits, model details, and usage guidance, making it complete for a search tool with rich annotations.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds contextual meaning, e.g., 'text you already pulled' and examples for query, which 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 does semantic search inside a fetched record, using specific verbs and resource. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the use case of reducing context size.

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 when to use: when the record is too big for the prompt. It also pairs with ask_pipeworx_grounded. It doesn't explicitly state when not to use, but the context is clear.

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

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

Adds behavioral context beyond annotations: OAuth requirement, delivery channel limits, phone verification, and 10/day SMS cap. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, 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?

Well-structured: purpose first, then requirements, types with examples, delivery channels. Slightly verbose but every sentence is informative. No fluff.

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

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

Covers types, params, delivery options, constraints. No output schema, but description mentions returned subscription ID. Lacks full return structure, but otherwise complete given annotations.

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

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

Schema coverage is 100%, but description adds significant meaning: explains each type with examples, details params structure, delivery object properties with constraints. Enhances 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 verb 'Create', the resource 'proactive monitoring subscription', and mentions the returned ID. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

Provides explicit context: requires OAuth account, supported types with examples, delivery channel constraints. Lacks explicit when-not-to-use or comparison to siblings, but clear usage context is given.

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, etc. The description adds valuable context beyond annotations: it reveals that the tool returns example questions with 'exact tool + argument shape' drawn from a 'live catalog'. This helps the agent understand the tool's behavior and output format.

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

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

The description is slightly verbose but well-structured: it starts with synonym queries, explains the output, then usage. Every sentence adds value, though it could be tightened without losing information.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers all necessary aspects: input, output format, usage context, and alignment with sibling tools. There are no obvious 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% with one optional string parameter. The description adds meaning by providing example focus areas ('finance', 'pharma', etc.) and explaining the effect of omitting vs. providing the topic. This goes beyond the schema's minimal description.

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

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

Description uses specific verbs ('returns category-bucketed example questions') and clearly distinguishes from sibling tools like ask_pipeworx and discover_tools by positioning it as the onboarding entry point. It also lists synonym user queries, making the purpose unmistakable.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing strong when-to-use guidance. It could be improved by explicitly stating when not to use it, but the context of sibling tools implies alternatives.

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

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

The description adds significant value beyond annotations: it explains ownership enforcement, deactivation instead of deletion, and that historical events remain available via 'recent_alerts'. This aligns with the non-destructive annotation.

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

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

The description is extremely concise with two sentences, front-loading the primary action and immediately providing critical behavioral context. 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?

For a simple tool with one parameter and no output schema, the description covers purpose, usage constraint, and outcome. It even links to a related sibling tool ('recent_alerts'), providing complete context.

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

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

Schema coverage is 100% and the parameter 'id' is well-described in the schema. The description does not add further semantic detail about the parameter itself, meeting the baseline.

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

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

The description clearly states the action 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by indicating it performs the reverse operation.

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 by enforcing ownership ('you can only cancel your own subscriptions') and explaining the deactivation behavior. It lacks explicit when-not-to-use guidance but is sufficient for a simple tool.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds critical behavioral context: it relies on SEC EDGAR + XBRL, supports only v1 company-financial claims, and details the return values (verdict, structured form, actual value with citation, percent delta). No contradictions with annotations.

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

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

The description is front-loaded with example queries, making the tool's purpose immediately clear. While slightly lengthy, every sentence adds value, covering usage, scope, and output. Could be marginally more 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 has only one parameter and no output schema, the description provides comprehensive information: domain, data sources, return structure, and replacement of multiple calls. It is fully adequate for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by giving concrete examples of the 'claim' parameter ('Apple's FY2024 revenue...') and specifying the natural-language format, which 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 specifies the tool's purpose as verifying natural-language claims, focusing on company-financial data. It includes example queries and distinguishes itself from sibling tools by replacing multiple sequential calls.

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 states when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and clarifies the domain (company-financial claims). It does not explicitly say when not to use, but the domain constraint is clear.

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