Geohash

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

Beyond annotations (readOnly, openWorld, idempotent, not destructive), the description adds important behavioral context: it probes multiple models, notes that workers-ai is free while Anthropic requires a BYO key with direct billing, and specifies the return structure (per-model and combined view). No contradiction with annotations.

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

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

The description is a single paragraph of about 100 words, front-loaded with the primary action. It is concise and informative without unnecessary fluff, though it could be slightly more streamlined.

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

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

Despite lacking an output schema, the description fully details the return format (per-model score, confidence, signals, raw_response, plus combined view). All input parameters are adequately explained, and the tool's behavior is clear enough 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?

With 100% schema description coverage, baseline is 3, but the description adds significant meaning: it clarifies that 'entity' can be a brand, product, or topic; explains that 'models' are optional and lists supported values; details that '_apiKey' is only needed for Anthropic and is passed directly; and notes that 'context' helps disambiguate. 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 uses specific verbs ('probe', 'score') and clearly identifies the resource (LLMs, visibility score). It distinguishes this tool from siblings like 'scan_competitor_ai_presence' or 'entity_profile' by focusing on AI visibility scoring across multiple models.

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

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

The description provides clear use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to use Anthropic (with API key). However, it does not explicitly contrast with similar tools or state when not to use this tool.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that it returns structured answers with stable pipeworx:// citation URIs, routes to 4,819 tools, and fills arguments. No contradictions.

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

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

The description is fairly long but well-structured: front-loaded with key recommendation, followed by examples and alternatives. Every sentence adds value. However, it could be slightly more concise; a few words could be trimmed without loss.

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

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

Given no output schema, the description adequately explains the return format (structured answer with citation URIs). It covers the scope of questions and mentions it handles various domains. Lacks mention of error handling or rate limits, but annotations imply safety. Complete enough for a complex tool.

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

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

Schema coverage is 100% (all 6 parameters described in schema). The description only repeats that the parameter is a natural language question and lists aliases, adding no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a preferred tool for factual questions about current or historical data, distinguishing itself from web search and sibling tools like ask_pipeworx_grounded and deep_research. It specifies the action (routes question to 4,819 tools) and the resource (authoritative structured data).

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

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

Explicitly says 'START HERE for most questions' and provides exactly when to use alternatives (ask_pipeworx_grounded for single hallucination-resistant answer, deep_research for broad multi-part questions). Includes concrete examples and notes it works on every tier.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the exact response format, refusal reasons, and the extra LLM call cost, exceeding annotation coverage.

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

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

The description is front-loaded with the key concept and provides all necessary details without redundancy. It is well-structured but slightly lengthy; however, every sentence adds value.

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

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

Given the complexity (6 aliased parameters, no output schema), the description fully explains the behavior, response format, refusal reasons, and usage context, making it complete for agent decision-making.

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

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

Schema description coverage is 100% with all parameters documented as aliases for the question. The description does not add further semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling 'ask_pipeworx' by specifying it extracts answers only from tool results with explicit refusal reasons.

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

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

Explicitly advises when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples, and when not to: 'prefer ask_pipeworx for casual lookups'.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds extensive context: fan-out mechanics, response shapes, resolver contract, parent event extraction, news fallback, safety short-circuits, and cancellation rule parsing, all consistent 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 verbose (600+ words) with extensive examples and detail. While well-structured, it could be more concise. Every sentence adds value, but the length may overwhelm agents.

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

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

Despite no output schema, the description thoroughly explains response shapes, error conditions, resolver confidence levels, parent event handling, news fallback, and cancellation rules. It covers all aspects needed for safe 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 covers all parameters (100%), but description adds value by explaining market input flexibility, depth options with defaults, and include_raw trade-offs between summary and full payload. This exceeds schema information.

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 researches Polymarket bets by pulling Pipeworx data, specifying input formats (slug, URL, question text) and use cases ('should I bet on X'). It distinguishes from sibling tools like polymarket_edges by focusing on comprehensive data gathering rather than edge calculation.

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 usage guidance ('Use for...') and explains when to avoid trusting results (low-confidence matches, closed markets). However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage, though the use cases are implied.

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

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

Annotations already provide safety and idempotency hints. Description adds key behaviors: correct handling of off-calendar fiscal years, results sorted by primary metric, and citation URIs per entity. 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?

Single paragraph packs many details efficiently, front-loaded with example queries. Could be slightly more structured (e.g., bullet points), but no wasted language.

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 specifies return format: paired data + citation URIs, sorted by primary metric. Covers both entity types comprehensively. Complete for a focused comparison 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%. Description enriches parameter meaning by explaining how 'type' selects data source and metrics, and 'values' specifics about tickers/CIKs and drug names with limits. Adds behavioral context beyond schema.

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

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

Clearly states it performs side-by-side comparison of 2-5 companies or drugs, pulling specific financial or adverse-event data. Distinguishes from sibling tools like entity_profile by focusing on comparative 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?

Explicitly provides example queries ('X vs Y', 'rank these companies') and instructs to prefer this over sequential single-pack lookups. Clearly defines when to use and implicitly when not to.

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

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

The description adds value beyond the annotations by specifying 'Keyless, offline' and detailing the output format. Annotations already indicate read-only, idempotent, and safe behavior, and the description reinforces this with concrete details.

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

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

The description is a single sentence that efficiently conveys purpose, output, and special features (keyless, offline). 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 tool with one parameter, full annotations, and no output schema, the description adequately covers return values (center coordinate and bounding box). Parameter documentation is sufficient via the schema. Complete for its complexity.

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

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

Schema coverage is 100% and the schema already describes the parameter with an example. The description adds no new semantics beyond the schema; it merely echoes the structure. Baseline 3 is appropriate.

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

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

The description clearly states the action (decode) and resource (geohash), and specifies the outputs (center coordinate and bounding box). This distinguishes it from sibling tools like `encode_geohash`.

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 'Keyless, offline' which provides useful context for when to use the tool (no authentication needed, works without network). However, it does not explicitly contrast with alternatives or state when not to use it.

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

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

Disclosures go beyond annotations: explains it decomposes questions into facets, routes to 4,819 tools in parallel, returns findings packet with verbatim evidence, confidence, source, fetched_at, stable citation, and explicit gaps[] for unanswered facets. Also notes 15-60s response time and that it never invents data. 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 verbose but well-structured: critical usage note first, then core functionality, then examples and disclaimers. Every sentence adds value. However, it could be slightly tightened without losing information, hence 4 rather than 5.

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

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

Despite no output schema, the description details the return format (findings packet). It covers prerequisites (account), limitations (not for breaking news), expected behavior (gaps, no invention), and time estimate. Complete for a complex tool.

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

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

Schema covers 100% of parameters with descriptions. The description adds significant value: explains depth enum values map to facet counts (quick=3, standard=5, thorough=8) and notes paid requirement for thorough. Provides example questions. This exceeds what the schema alone offers.

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

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

The description clearly states the tool performs grounded multi-source research across 1259 structured data sources in one call, explicitly distinguishing it from sibling tools like ask_pipeworx for single lookups and breaking news. It specifies it is not open-web search, making its purpose unambiguous.

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

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

Provides explicit guidance: account required, use ask_pipeworx if not signed in, for single lookup use ask_pipeworx, for breaking news prefer ask_pipeworx. Also mentions paid plan for 'thorough' depth. This leaves no ambiguity about when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by revealing that results include 'full input schemas (with curated examples)' and that 'each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations to explain the tool's output format and immediate usability.

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-loading the purpose and usage. However, the first sentence includes a long list of domains ('SEC filings, financials, ... stocks') which makes it slightly verbose. It earns its place but could be trimmed.

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 that there is no output schema, the description adequately explains the return value: 'tools with names, descriptions, and full input schemas (with curated examples).' It also states the tool is for discovery and should be called first. This is sufficient for the tool's complexity and 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% with all 6 parameters described. The description does not add new parameter semantics beyond what the schema already provides; it only reinforces that the 'query' parameter accepts natural language. With full schema coverage, the baseline is 3, and the description does not compensate further.

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

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

The description explicitly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and clarifies that it returns top-N relevant tools with schemas. This clearly distinguishes it from sibling tools like deep_research or ask_pipeworx, which answer queries rather than discover tools.

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

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

The description tells the agent to 'Use when you need to browse, search, look up, or discover what tools exist' and explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context but does not explicitly state when not to use it (e.g., if the tool is already known).

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

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

Annotations already cover readOnly, idempotent, non-destructive behavior. Description adds value with 'keyless, offline' and precision effect (more chars = smaller cell), enhancing transparency beyond annotations.

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

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

Two concise sentences: first states purpose, second explains precision. No extra words, front-loaded, 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?

Describes input (lat/lon, precision) and output (geohash string). No output schema, but description adequately explains return. Considering sibling decode_geohash, a minor improvement could mention geohash format, but current is sufficient.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning to precision by explaining the effect on cell size, going beyond the schema's length 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 clearly states the tool encodes latitude/longitude to a geohash string. It distinguishes from sibling decode_geohash and notes keyless/offline nature.

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

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

The description implies usage for converting coordinates to geohash but lacks explicit guidance on when to use versus alternatives like decode_geohash. Context is sufficient but not prescriptive.

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 rich behavioral details: fanning across multiple sources, returning specific fields, noting patent sunset soft-fail, and name unsupported. No contradiction.

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

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

Description is somewhat lengthy but well-structured with bullet points and examples. Front-loaded with query examples. Could be slightly trimmed but remains valuable without fat.

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

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

No output schema, so description bears full burden. It carefully enumerates all returned components (cik, filings with URIs, fundamentals, patents, news, LEI) with details like limits and fallbacks. Complete for a complex tool.

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

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

Schema coverage 100% (baseline 3). Description adds meaning: value can be ticker or CIK, names not supported; type only 'company' supported. Adds beyond schema but not excessively.

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 like 'profile', 'brief me on', and lists example queries. It clearly states it provides a full cross-source profile of a US public company. Differentiates from siblings by stating 'ALWAYS PREFER over chaining single-pack lookups'.

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

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

Explicitly says when to use (holistic view) and when not (only names, then use resolve_entity). Provides example queries and fallback behavior for patents. Guides agent to prefer this over chaining 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?

The description's 'delete' aligns with destructiveHint=true annotation, and adds context about clearing sensitive data. It does not contradict annotations and provides useful behavioral nuance beyond the schema.

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: purpose, usage guideline, and sibling reference. Every sentence earns its place, front-loaded, no waste.

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

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

For a simple tool with one param, no output schema, and clear annotations, the description is complete: purpose, when-to-use, and sibling context are all covered.

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 description 'Memory key to delete'. The tool description adds 'by key' but no extra detail compared to schema. Baseline of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', using specific verb (delete) and resource (memory by key), and distinguishes itself from siblings like remember and recall.

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

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

Provides explicit guidance on when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with remember and recall, offering clear alternatives.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. Description adds concrete behavioral details: fetches page, extracts specific elements, outputs markdown, and suggests placement. Exceeds annotation coverage 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?

Three concise, front-loaded sentences. First sentence states purpose, second explains process, third lists use cases. No redundant or filler content.

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

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

Despite missing output schema, description fully explains the return value (single text blob, format, placement). Covers what, how, output, and use cases. Complete for a straightforward tool.

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

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

Schema covers both parameters with descriptions (100% coverage). Description does not add additional semantics for the parameters themselves, only contextualizes the overall behavior. 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?

Clearly states 'Generate a production-ready llms.txt file for any URL' with specific verb and resource. Distinct from siblings, which cover entirely different domains.

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

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

Lists multiple explicit use cases (client sites, personal projects, competitor auditing) but does not explicitly contrast with siblings or state when not to use. However, given no sibling overlap, the guidance is effective.

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, making behavioral traits clear. The description adds value by listing return fields but doesn't go beyond what annotations provide for safety.

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 well-structured sentences: front-loaded with action and output, followed by usage context. No superfluous 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 low complexity (one optional parameter, no output schema), the description provides all necessary information: purpose, return fields, and usage 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% with a clear description for include_inactive. The tool description does not add additional parameter meaning beyond what the schema provides.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the return fields (id, type, params, etc.). While it doesn't explicitly differentiate from siblings, the context of subscribe/unsubscribe makes the purpose clear.

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 usage guidance: use to review before adding more subscriptions or to find an id to cancel. Implies when-not by omission of modification actions.

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

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

Annotations provide no specific behavioral details, but the description adds important traits: rate-limited to 5 per identifier per day, free, doesn't count against quota, and that the team reads digests daily. 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 main purpose, followed by usage scenarios, writing tips, and meta information. It is slightly verbose but every sentence adds value. A minor improvement could be to condense the usage scenarios.

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 (sending feedback), no output schema is needed. The description covers why to use, how to write feedback, and constraints like rate limiting and quota. The schema covers the context object, so the description is complete for an agent to select and use the tool.

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

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

Schema coverage is 100%, so the description doesn't need to repeat parameter details. However, it adds useful context: message should be 1-2 sentences typical, 2000 chars max, and be specific. The type enum is already explained in the schema, so the description adds marginal but helpful 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?

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses a specific verb ('Tell') and resource ('Pipeworx team something is broken, missing, or needs to exist'), and distinguishes from sibling tools, none of which serve a similar feedback function.

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

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

The description provides explicit when-to-use scenarios: for wrong/stale data (bug), missing tool (feature/data_gap), or positive note (praise). It also advises describing the issue in terms of Pipeworx tools/packs and not pasting end-user prompts, offering clear guidance for appropriate use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data source, privacy, data shape, and caching behavior beyond annotations.

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

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

The description is a single concise paragraph. First sentence states the output and parameters, then a numbered list of use cases, then data source details. Every sentence adds value with no redundancy.

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

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

The tool has low complexity (one optional parameter, no output schema). The description covers what is returned (top tools, top packs, total call volume), caching behavior, and data source. It provides sufficient context for an agent to invoke correctly.

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

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

Schema coverage is 100% with a parameter description. The description adds extra semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides usage insight beyond the schema's enum description.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It mentions the resource (Pipeworx trending) and action (returns). Among siblings, it's unique as a trending/discovery tool, distinguishing it from ask_pipeworx or pipeworx_feedback.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming canonical choice, and checking alignment. It does not explicitly state when not to use or list alternatives, but the use cases give clear guidance on appropriate contexts.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds rich behavioral context: monotonicity violations, partition checks, Jaccard similarity filter (0.30), placeholder filter (>20% returns null), fill check mechanism explaining when not to trade, and response structure. No contradictions with annotations.

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

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

The description is quite long and dense with technical details. However, it is well-structured: first sentence gives purpose, then explains modes in sections, then details semantic anchor, partition filter, response, and fill check. Every sentence adds value, but could be slightly more concise for rapid scanning.

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

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

No output schema, so description must cover return values. It describes the response structure: opportunities array with gap_pp, suggested_trade, reasoning, monotonicity context; event mode includes partition_check with sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade; fill check details theoretical vs realizable edge. This is comprehensive for a complex tool.

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

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

Input schema has 100% description coverage for two parameters, but the tool description adds significant meaning: event parameter accepts slugs or full URLs, topic is a seed question, and explains the behavior triggered by each parameter. This goes beyond schema descriptions.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes (trending scan, event, topic) and distinguishes them effectively. The verb 'find arbitrage opportunities' is specific and the resource (Polymarket) is explicit.

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

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

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' Recommends event for specific markets and explains cross-event catches patterns single-event misses. Also references polymarket_fill_risk for custom sizing, guiding alternative 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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds significant behavioral context: it caches results for 1h keyed on all knobs, discloses Fed bets are excluded from ranking, and explains diagnostic outputs. This goes well beyond the annotations.

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

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

The description is lengthy but well-organized with sections and emojis. Every sentence adds value, though it could be slightly more concise. It front-loads the core purpose 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 (9 parameters, no output schema), the description is remarkably complete. It covers caching, filter behavior, diagnostic info, and the edge calculation methodology. An agent has all information needed to select and invoke the tool correctly.

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

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

All 9 parameters have descriptions in the schema (100% coverage). The description adds value by explaining how parameters interact (e.g., 'Tradeable-edge filter', 'Bump for very thin partitions') and providing rationale for defaults. While the schema already documents each parameter, the description enriches understanding.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from sibling tools like polymarket_arbitrage by detailing three model families and emphasizing it's built for 'what should I bet on today' without paging through hundreds of markets.

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

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

The description provides extensive usage context, including knobs like min_liquidity, max_spread_pp, and explains when to adjust slippage. However, it lacks explicit instructions on when NOT to use this tool versus alternatives like polymarket_arbitrage, leaving some interpretation to 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 declare the tool as read-only, idempotent, and non-destructive. The description adds substantial context: snapshot TTL (60-day), decay computation method (daily closes, not intraday), gaps meaning no scan, and the distinction between tracked and expired. No contradiction.

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

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

The description is detailed but well-structured, starting with the core question and then elaborating on response fields and limits. Every sentence contributes information, though it could be slightly more terse.

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

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

Without an output schema, the description fully describes the response structure (tracked, expired, snapshot_dates) and the limitations (TTL, computation basis). For a tool with no required parameters and rich annotations, this is complete and actionable.

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%, baseline 3. The description adds value by explaining default values (14 days, '1wk'), clamping range (2-30), and the concept of window families, 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's purpose: answering 'how long has this edge existed and is it shrinking?' and provides specific context about edge persistence and decay telemetry. It distinguishes from the sibling polymarket_edges by focusing on temporal analysis rather than raw snapshots.

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

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

The description implies usage through the contrast between a fresh wide edge and an old one, indicating when the tool is valuable. It does not explicitly state alternatives or when not to use it, but the context is clear.

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

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

Annotations (readOnlyHint true, idempotentHint true) already indicate safety; description adds rich behavioral detail: walks order book ladder, returns verdict and fill metrics, warns about thin books and partial fills converting arb into unhedged position. 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 well-structured with clear sections and front-loaded purpose, but somewhat verbose. Every sentence adds value, but a few could be tightened without loss. Efficient but not maximally 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 no output schema, the description compensates by detailing return fields for both modes. It covers parameter usage, behavioral risks, and when to invoke. Combined with complete input schema and annotations, it is fully informative for correct tool selection and 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 covers 100% of parameters with descriptions. Description adds further context: side default and auto behavior in basket, event/market slug/URL examples, size_usd interpretation for single-market vs basket (settlement notional). This adds significant meaning beyond schema.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly contrasts with siblings by advising use before acting on polymarket_arbitrage or polymarket_edges signals.

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

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

Explicit 'USE THIS before acting on...' guidance, with specific conditions (polymarket_arbitrage SELL/BUY-EVERY-LEG signal, edges trade above ~$500). It also explains why (theoretical overround not capturable, partial fills cause directional risk) and requires one of `market` or `event`.

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

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

The description goes well beyond annotations, explaining safety fields like compatibility_warning, temporal_alignment, and skipped_cross_counters. It discloses when spreads are mathematically meaningless and exposes internal comparisons, providing full transparency without contradicting the readOnlyHint and idempotentHint annotations.

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

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

The description is detailed but well-structured with clear sections for modes, response, and safety fields. It is front-loaded with the main purpose. While slightly long, every sentence provides value, so conciseness is good.

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

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

Despite having no output schema, the description thoroughly explains the response format (probabilities, top_spreads_pp, safety fields). It covers all nuances of cross-venue spreads, temporal alignment, and compatibility warnings, making it fully contextual for a complex tool.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds context by explaining the topic shortcuts, how override works, and providing format examples. This adds value beyond the schema, justifying a 4.

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

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

The description clearly states it calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by focusing on this specific comparative analysis, which no other sibling 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?

The description explicitly explains two modes: topic shortcuts for common macros and explicit tickers for custom pairs. It also warns that pre-mapped topics often return a compatibility warning, guiding the agent when to use which mode and when spreads are meaningful.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: the behavior when omitting the key (list all), scoping to identifier, and the 'without re-deriving' phrasing. No contradictions.

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

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

The description is roughly four sentences compactly covering purpose, usage, pairing, and scope. No filler or redundancy; front-loaded with the core action.

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

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

Given the tool's simplicity (one optional param, no output schema), the description fully covers what it does, how to use it (with/without key), scope, and relationship to siblings. No additional information is needed for correct invocation.

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

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

Schema description coverage is 100% and the schema already describes the key parameter's purpose and the omit-to-list behavior. The description repeats this information without adding new param details, so baseline 3 is appropriate.

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

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

The description explicitly states the action ('Retrieve a value' or 'list all saved keys') and the resource (previously saved values via remember). It also distinguishes from sibling tools by mentioning 'remember' and 'forget' as counterparts, providing clear context.

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

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

The description gives concrete use cases (look up target ticker, address, research notes) and states when to use it ('without re-deriving from scratch'). It also notes scoping and pairing with remember and forget, but lacks explicit when-not-to-use or alternatives beyond these two.

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 and idempotent. The description adds that mark_read:true can mutate read state, which is important. No contradictions.

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

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

The description is concise with three sentences, front-loaded with the purpose, and no unnecessary words.

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

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

Despite no output schema, the description specifies return fields (source, citation_uri, raw payload), mentions alternative access, and covers key usage scenarios. Very complete for a read-only tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds usage context for type, since, and mark_read, but does not cover limit or unread_only. Overall adds 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?

The description clearly states it pulls fired events from the subscription feed and returns most recent alerts with specific fields. However, it does not explicitly differentiate from sibling tools like list_subscriptions, which could cause confusion.

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 useful guidance on polling and an alternative GET endpoint for scripts/dashboards. It mentions filtering by type and since, but lacks explicit when-not-to-use or comparison with 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 are readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, indicating safe, read-only behavior. The description adds context: fans out to multiple sources, soft-fail for USPTO, accepts ISO/relative time, and returns citations. No contradictions.

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

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

The description is concise yet comprehensive, front-loaded with examples, and efficiently explains behavior, sources, and parameters 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 lacking an output schema, the description details return format (structured changes grouped by source, count, citation URIs). It covers all required parameters, expected behavior, and alternatives, making it complete for the tool's complexity.

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

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

Schema descriptions cover all parameters (100% coverage). The description adds usage guidance: 'since' accepts ISO or relative (suggests '30d' or '1m'), and 'value' can be ticker or CIK. This enhances clarity beyond schema alone.

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

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

The description clearly states the tool's purpose: providing a change feed for a company over a time window, with examples of queries. It explicitly distinguishes from sibling tool 'entity_profile', which returns static profiles.

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 includes example queries and suggests when to use 'entity_profile' instead. It also explains fallback behavior (GDELT→GNews) and parameter suggestions (e.g., '30d' for monitoring), but does not explicitly list all cases when not to use the 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?

Discloses scoping by identifier, persistence for authenticated users (persistent) vs anonymous (24 hours). Adds 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?

Concise yet complete: each sentence adds value. Front-loaded with purpose, then usage, then behavior, then pairing.

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 good annotations and schema, the description covers all necessary aspects: purpose, usage, behavioral details, and related tools.

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

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

Schema already describes both parameters with 100% coverage. Description adds examples but no significant extra 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?

Clearly states 'Save data' and specifies reuse across conversations/sessions. Distinguishes from sibling tools recall and forget 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?

Explicitly lists when to use: when discovering something worth carrying forward, with concrete examples. Also mentions pairing with recall/forget.

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

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

Discloses that each call internally cascades through several lookup endpoints, and documents return formats (ticker, CIK, RxCUI, citation URIs). Annotations already indicate safe read-only, idempotent behavior; description adds valuable implementation detail 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?

Well-structured with front-loaded examples and detailed type breakdowns. Slightly long at ~5 sentences but 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, so description fully explains return values (ticker, CIK, RxCUI, etc.) and internal cascading. Covers all necessary context for an agent to use the tool correctly.

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

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

Description adds significant meaning beyond schema: explains what each entity type returns (e.g., company yields ticker + CIK + company_name + citation) and gives example values for the 'value' parameter. Schema coverage is 100% but description enhances usability considerably.

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 starts with concrete example queries ('What's the ticker for…') and states it resolves names to canonical IDs. It lists supported entity types with specific return values, clearly distinguishing this tool from siblings that operate on already-resolved identifiers.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID.' Notes that it replaces 2-3 manual lookups, implying when this tool is the right choice. No need for when-not, as siblings like entity_profile expect IDs as input.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: probes each entity with ai_visibility_check, ranks by score, identifies most/least recognized, treats the first entity as the 'subject' for narrative, and specifies output fields (score, confidence, signal density). No contradictions.

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

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

The description is three well-structured sentences plus a parenthetical example, front-loading the core action and purpose. Every sentence adds value without redundancy or filler.

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

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

With no output schema, the description adequately explains return values as a ranked list with score, confidence, and signal density per entity. While the exact format is unspecified, the coverage is sufficient for a moderately complex tool with 4 well-documented parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'context' parameter for disambiguation, noting that the first entity in 'entities' is treated as the subject for narrative, and clarifying that 'models' defaults to workers-ai. 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 AI visibility across multiple entities side-by-side,' identifies the resource as 'AI presence,' and distinguishes from sibling tools like ai_visibility_check (single-entity) and compare_entities (general comparison) by specifying ranking and competitive audit 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?

The description provides explicit context for use ('competitive AI-marketing audits') and gives an example question, but does not explicitly state when not to use or list alternative tools. It implies that ai_visibility_check is used internally, so agents might infer single-entity use cases for that 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 (readOnly, idempotent), it discloses partial failure behavior (bundlephobia timeout), timing (5-30s for first measurement), and return structure (summary block, advisories, links, alternatives).

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 contains all information but is dense. Could benefit from bullet points or sections, but it is front-loaded with the main value and every sentence is meaningful.

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 fully explains the output fields, behavior on partial failures, and ecosystem scope. This is sufficient for an agent to invoke and interpret results.

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

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

Input schema covers both parameters with descriptions, but the description adds that scoped packages are accepted for 'package' and that 'version' defaults to latest. This provides extra context not in 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 a composite check for evaluating npm packages, combining data from deps.dev and bundlephobia. It specifies the resource (npm package) and distinguishes itself from sibling tools like deep_research by focusing on dependency 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?

Explicitly says when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also notes NPM-only in v1 and directs other ecosystems to deps.dev directly.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds significant behavioral context: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, caps input at 200K chars with truncation and flagging, and returns offsets for verification. No contradictions.

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

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

The description is ~5 sentences, front-loading the core purpose and usage guidance. Every sentence adds essential information: purpose, when to use, pairing, technical details, and capabilities. No filler, well-structured.

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

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

Despite no output schema, the description explains what is returned (passages with offsets and scores), the input cap, and the pairing with another tool. It covers both the 'what' and 'why', leaving no critical gaps for an agent to understand correct usage.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances meaning by explaining the query is natural-language, the embedding model and method, and that offsets are returned for quote verification. This goes beyond the schema descriptions, justifying a 4.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record', specifies input (text, query) and output (top-N passages with character offsets and similarity scores). It distinguishes from siblings by mentioning pairing with 'ask_pipeworx_grounded' for grounding, making the purpose unambiguous.

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

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

The description explicitly tells when to use: 'Use when the record is too big to cram into the prompt'. It provides an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document'. This gives clear guidance on context and exclusions.

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

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

The description adds behavioral context (auth requirements, delivery constraints, webhook handling) but contradicts annotations: idempotentHint=true suggests safe retry, yet description says 'Returns the new subscription id' implying non-idempotent behavior. This inconsistency confuses the agent.

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

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

The description is fairly long but well-structured: main purpose first, then type details, then delivery channels. Every sentence adds unique information. Could be slightly more concise, but overall efficient for the complexity.

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

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

Given the tool's complexity (3 params including nested objects, no output schema), the description is highly complete. It covers return format (subscription ID), delivery channel behavior, auth prerequisites, and type-specific params. All necessary context for correct invocation is present.

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

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

Schema coverage is 100%, and the description adds substantial value by explaining each type with examples, detailing param objects for each type, and elaborating on delivery sub-schema (email, SMS, webhook). This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb (create) and resource (subscription), and distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation and proactive monitoring.

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 (create a subscription) and provides constraints (requires Pipeworx OAuth account, anonymous/BYO cannot persist). It also details supported types and delivery channels, though it lacks explicit when-not-to-use or alternatives for similar tasks.

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

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

Description adds value beyond annotations by detailing the return format (category-bucketed examples with exact tool+argument shapes) and behavior with/without topic. 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 comprehensive but slightly lengthy; however, all sentences add value and the structure front-loads purpose.

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

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

For a tool with no output schema, description fully explains return value and source (live catalog), covering all needed context given low parameter complexity.

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

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

Schema already describes parameter well; description adds value by explicitly listing topic options and explaining behavior difference when omitted vs provided.

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

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

The description clearly states the tool is the onboarding entry point for suggesting questions about Pipeworx, lists alternative phrasings, and explains what it returns (category-bucketed examples with tool+argument shapes).

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' and provides guidance on optional topic parameter.

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 destructiveHint=false, and the description clarifies that the row is deactivated, not deleted, preserving historical events. This adds valuable behavioral context beyond annotations.

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

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

Two sentences convey the purpose, ownership constraint, and behavioral effect. Front-loaded with the action, no extraneous words. Highly efficient.

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

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

For a single-parameter tool with no output schema, the description covers all necessary context: action, ownership, and data retention. Complete for the complexity.

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

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

Schema coverage is 100%, so the schema already documents the parameter well. The description adds no new meaning beyond stating it is the id from subscribe, which is minimally helpful. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription') and the resource ('by id'). It distinguishes itself from the sibling 'subscribe' by specifying cancellation.

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 includes ownership enforcement ('you can only cancel your own subscriptions'), which gives clear context for usage. It does not explicitly mention alternatives like 'list_subscriptions' for finding owned subscriptions, but the context is sufficient.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds valuable context: the types of verdicts returned (confirmed, refuted, etc.), the inclusion of citations and delta, and the limitation to v1 supporting only company-financial claims. This goes beyond the annotations to manage agent expectations.

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

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

The description is two sentences long, with key information front-loaded. It immediately conveys the tool's purpose, provides concrete examples, states the domain, and summarizes benefits. Every sentence earns its place without unnecessary detail.

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

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

Given the simple input (single string parameter) and the absence of an output schema, the description covers all necessary aspects: how to invoke (natural-language claim), what it does (verify against sources), what it returns (verdict, structured form, value, citation, delta), and its limitations (v1, financial claims only). No gaps are apparent.

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

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

The sole parameter 'claim' has a clear schema description with examples, achieving 100% coverage. The description text reinforces this with additional examples and context about the type of claims supported. Since the schema already sufficiently describes the parameter, the description adds minimal extra semantic value.

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

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

The description opens with common query patterns like 'Is it true that...' and 'fact check', immediately clarifying the tool's purpose as natural-language claim verification. It specifies supported domains (company-financial claims) and data sources (SEC EDGAR + XBRL), distinguishing it from sibling tools that perform other research or analysis tasks.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct', providing direct guidance on when to invoke the tool. It also highlights efficiency gains by replacing multiple sequential calls. However, it does not explicitly state when not to use it or list alternative tools for non-financial claims.

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