Easypost

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description adds valuable context: it probes multiple LLMs, requires an API key for Anthropic (with cost implications), and returns per-model details. This does not contradict any annotation and provides useful behavioral insight beyond the structured data.

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

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

The description is concise (3-4 sentences) with no redundant information. It is front-loaded with the core action and output, then provides model details and use cases. Every sentence adds value, achieving high informational density without verbosity.

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 explains the return format (per-model score, confidence, signals, raw_response, combined view) and use cases. It covers the tool's purpose adequately for a 4-parameter tool. Minor omissions like rate limits or error handling are acceptable given the idempotent/read-only annotations, but slightly less complete than ideal.

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 each parameter described. The description reinforces the meaning of `_apiKey` (BYO key, pay directly) and context parameter (disambiguation). It adds a layer of understanding about default model and usage, which goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the verb 'probe', the resource 'LLMs', and the unique output format. This distinguishes it from sibling tools like 'scan_competitor_ai_presence' which have a different focus.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use (e.g., checking brand visibility) and provides context on default versus paid models. However, it does not explicitly mention when not to use or compare directly with similar sibling tools like 'scan_competitor_ai_presence', which slightly reduces the score.

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?

Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description adds critical behavioral context: it routes to 5,529 tools across 1,455 sources, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and mentions it works on every tier with one fast call. This goes beyond the annotations to explain how the tool behaves and what the user can expect.

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

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

The description is long but every sentence carries value: it starts with a strong directive, lists covered domains, gives examples, explains routing, and contrasts with alternatives. It is front-loaded and organized, though slightly verbose with the extensive example list. It earns a 4, not 5, because the length could be trimmed without losing core guidance.

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

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

This tool has a simple input schema (one required string) but no output schema. The description compensates fully by explaining what the output looks like (structured answer with citations), when to use it, and how it relates to siblings. It also addresses tier availability and breaking news use cases, making the description complete for all practical usage scenarios.

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

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

The schema already covers 100% of parameters with descriptions for 'question' and its five aliases, plus examples. The description itself adds little parameter-specific detail, but the baseline of 3 is appropriate because the schema does the heavy lifting. The description does reinforce that the parameter expects a natural-language question, but no new semantic info is added 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 identifies the tool as a query router for factual questions requiring authoritative structured data with citations. It explicitly distinguishes itself from siblings by contrasting with ask_pipeworx_grounded and deep_research, and specifies the types of questions it handles (SEC filings, FDA data, FRED/BLS, etc.). This goes well beyond a vague 'ask a question' and gives precise 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?

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and gives concrete triggers like 'what is', 'look up', 'find', 'get the latest'. It also includes clear when-not-to-use guidance by naming alternatives for hallucination-resistant answers (ask_pipeworx_grounded) and broad multi-part questions (deep_research). This is exemplary usage guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses that it is an experimental edge with candidate routing improvements enabled live, that no candidate is currently active, and that it falls back to nothing—it is a full working router. This adds meaningful operational context about variable behavior over time, which annotations do not cover.

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 and front-loaded with the core identity ('Beta version of ask_pipeworx'). Each sentence provides necessary context: what it is, current state, and usage guidance. Slightly verbose but no wasted words.

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

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

For a router tool with no output schema, the description covers the essential context: it references the same response shape as ask_pipeworx, explains the experimental nature, the fallback behavior, and how results are used. It does not explain return values explicitly but the reference to ask_pipeworx fills that gap.

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 already provides 100% coverage, documenting all six parameters with question as the canonical one and five aliases. The description adds no parameter-level detail, but given the high schema coverage, no compensation is needed. Baseline 3 applies.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and response shape. It distinguishes itself from the sibling ask_pipeworx by being the experimental edge, and explicitly confirms it is a full working router. However, it relies on the reader knowing what ask_pipeworx does rather than describing the routing function in standalone terms.

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

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

The description gives explicit usage context: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. It also clarifies the current state (no active candidate, matches ask_pipeworx exactly). It does not explicitly say when NOT to use it, but the beta/experimental framing implies caution for stable use cases.

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

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

The description goes far beyond the annotations by detailing the internal routing across 5,529 tools and 1455 sources, the extraction process, and the exact output structure including refusal reasons. It also discloses the extra LLM call cost. No contradiction with the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint 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 somewhat long but each sentence adds meaningful content: purpose, mechanism, output schema, usage guidance, and cost trade-off. It is front-loaded with the core differentiator ('Hallucination-resistant'). No fluff, though slightly dense.

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

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

Despite having no output schema, the description fully specifies return values (success and refusal formats) and refusal_reason enums. It also explains the difference from ask_pipeworx, use cases, and cost implications, 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?

The schema already provides 100% coverage for the single logical parameter 'question' with aliases and a clear description. The tool description does not add parameter-level details, but the baseline of 3 is appropriate because the schema handles parameter semantics fully.

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 'Hallucination-resistant answer mode for high-stakes reads,' clearly specifying the tool's function and distinguishing it from the sibling tool ask_pipeworx by noting 'Same routing as ask_pipeworx' but with extraction limited to the tool result. It explicitly names the use case and contrasts with ask_pipeworx for casual lookups, so it fully differentiates from siblings.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also states when not to use: 'prefer ask_pipeworx for casual lookups,' and names the alternative 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?

The description extensively covers behavior beyond annotations: safety (low-confidence match short-circuits), closed markets, wide spread warnings, resolution-rule risk, response shapes, resolver contract, parent event extractor, and news fallback details. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and complemented by this detailed behavioral context.

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

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

The description is thorough but quite long, spanning multiple paragraphs with detailed lists and examples. While front-loaded with a clear summary, it includes extensive specifics (e.g., Fred series codes, specific classifiers) that could be streamlined for better conciseness without losing essential guidance.

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

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

Given the tool's complexity (classifiers, fan-out, edge cases), the description is remarkably complete. It covers response shapes, resolver contract, parent event extraction, news fallback, safety checks, and resolution-rule risk. Since there is no output schema, the description compensates fully, leaving no critical 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 descriptions for all three parameters (market, depth, include_raw). The description adds significant value by explaining the three input types for market, the effect of depth (quick vs thorough), and the implications of include_raw on response size. This goes beyond the schema alone.

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

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

The description clearly states the tool's purpose: to research a Polymarket bet by pulling relevant Pipeworx data in one call. It specifies input formats (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear use cases. It also includes examples of fan-out for different bet types. However, it does not explicitly state when NOT to use this tool, such as when a simpler tool might suffice.

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 idempotentHint=true. The description adds useful behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

The description is well-structured and front-loaded with common query patterns. Every sentence adds value, and there is no unnecessary repetition 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?

Despite no output schema, the description explains that it returns paired data with citation URIs and that results are sorted by primary metric. This is sufficient for understanding the output. Could mention error handling or edge cases, but not required.

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

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

With 100% schema coverage, the description goes far beyond by explaining what data each 'type' pulls, giving examples for 'values', and clarifying input formats (tickers/CIKs for companies, drug names).

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

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

The description clearly states that this tool performs side-by-side comparison of 2-5 companies or drugs in one call. It distinguishes from siblings by explicitly preferring over sequential lookups and providing specific data sources for each type.

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 clear usage guidelines with example queries and explicitly states to prefer this over sequential single-pack lookups. However, it does not mention exclusions or when not to use it against sibling tools like entity_profile.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds critical behavioral context: account/auth requirements, paid plan for thorough, latency expectations, gaps[] never invented, contradictions[], citation_uri resolvability, semantic excerpting, and hop behavior. It richly describes operational traits without contradicting annotations.

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

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

The description is long but every sentence contributes operational value—auth, usage boundaries, output structure, latency, and edge cases. It is front-loaded with account requirements and core function. Slightly dense but appropriately so for a complex tool, so it earns a 4 rather than a 5.

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

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

Given the tool's complexity (decomposition, parallel routing, multi-hop, contradictions), the description covers return format, failure behavior (gaps[]), citation semantics, auth, latency, and edge cases. Without an output schema, it provides a thorough mental model for an agent to understand what happens and what to expect, making it highly complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates depth parameter nuances (paid for thorough, hop behavior) but the schema already includes these details. It does not add new meaning beyond what the schema provides, so it meets but does not exceed 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 uses specific verbs and resources: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in 'ONE call'. It clearly distinguishes from siblings by explicitly contrasting with ask_pipeworx and stating this is NOT open-web search, making it easy for an agent to know exactly 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 when-to-use guidance is given: 'Best for broad/multi-part questions over structured data'. It also provides clear exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. This level of directional guidance is exemplary.

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=true, idempotentHint=true, destructiveHint=false. Description adds beyond annotations by stating 'each result is ready to call directly, no second schema lookup needed' – a key behavioral trait. No contradictions.

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

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

The description is front-loaded with purpose and use cases, then details on return format. It is comprehensive but slightly verbose; could be tightened by removing redundant aliases list. Still well-structured and informative.

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 (6 parameters, diverse domains, no output schema), the description covers when to use, what it returns (top-N tools with full schemas), and how to call it. It is complete and guides effective invocation.

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

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

Schema coverage is 100% with all 6 parameters described. The description does not add significant new meaning beyond what the input schema provides; it mainly restates purpose. Baseline score of 3 is appropriate as schema does the heavy lifting.

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: 'Find tools by describing the data or task.' It specifies verb (find/discover), resource (tools), and distinguishes its role as a discovery tool to be called first, differentiating it from sibling 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 states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' with specific domains listed. Also instructs to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context and exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds an example but does not disclose additional behavioral traits like API key authentication or rate limits beyond what the schema provides. 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?

Two sentences: one explains functionality, one provides example. No wasted words, front-loaded with purpose. Perfectly concise 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?

Parameters fully documented in schema, description explains output (multi-carrier rates with price, service, delivery days). Lacks explanation of error cases (e.g., invalid zip) but this is acceptable given low tool complexity and rich 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 clear parameter descriptions. The description adds value by providing a concrete usage example showing how parameters combine (e.g., from_zip, to_zip, weight_oz, _apiKey), which aids understanding beyond the schema alone.

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

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

The description clearly states it 'Get shipping rate quotes' with specific source/destination and parcel, and lists return fields (multi-carrier rates, price, service level, delivery days). This distinguishes it from sibling easypost_track (tracking) and provides a concrete verb+resource.

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

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

The description implies usage for rate quotes but does not explicitly state when to use over alternatives like easypost_track. No 'when-not' or prerequisite guidance is provided; the context is implicit via the example.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds specific details about the return payload (current status, carrier, estimated delivery date, scan events), providing useful behavioral context beyond the annotations. No contradiction.

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

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

Two sentences plus a short example. The first sentence states purpose and return fields. No filler, all content earns its place. Front-loaded with the most important 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 read-only tracking tool with no output schema, the description covers what the tool returns (status, carrier, estimated delivery, scan events). Parameters are fully covered by schema. Could mention edge cases (e.g., invalid tracking code) but is sufficiently complete for common use.

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

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

Schema coverage is 100% with each parameter having a description. The description adds an example call showing actual values and optionality of carrier. This is marginally helpful but does not significantly expand on the schema's documentation.

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

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

The description begins with a clear verb 'Track a package by tracking number' and specifies the resource (package) and input (tracking number). It lists return fields (status, carrier, estimated delivery date, recent scan events), distinguishing it from sibling 'easypost_rates' which handles rate 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?

The description provides an example call but no explicit guidance on when to use this tool versus alternatives (e.g., when needing tracking vs. rates). It does not state when not to use it or mention prerequisites beyond the API key.

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 it as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it fans out across multiple sources, returns specific fields, mentions the USPTO patent soft-fail due to API sunset, and describes a fallback mechanism for news (GDELT→GNews). 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 relatively long but front-loaded with example queries, making the purpose immediately clear. Every sentence provides essential information; no fluff. Could be slightly more concise, but it earns its length.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description covers the return fields thoroughly, including caveats like patent soft-fail and news fallback. It mentions filing URIs and fundamentals with sorting. However, it doesn't specify pagination or limits beyond 'up to 5' filings, which is a minor gap.

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 that 'value' accepts ticker or zero-padded CIK, and that names are not supported (use resolve_entity). It also provides concrete examples like 'AAPL' and '0000320193', which is helpful beyond the schema 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 provides a 'full cross-source profile of a US public company in ONE parallel call.' It includes example queries and explicitly lists all returned data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It also distinguishes itself from sibling resolve_entity by specifying 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 explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and notes that names are not supported, directing users to use resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and when to use it, but doesn't contradict annotations. It reinforces the destructive nature without adding major new behavioral traits.

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: purpose, usage guidelines, and sibling reference. Every sentence provides necessary information without 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?

The tool is simple with 1 parameter, no output schema, and clear annotations. The description covers purpose, when to use, and related tools, making it fully informative for an agent.

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

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

Schema coverage is 100% and the only parameter 'key' is described in the schema as 'Memory key to delete'. The description adds 'by key' which matches. No additional meaning is provided 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 states 'Delete a previously stored memory by key' which clearly specifies the action (delete) and the resource (memory by key). It also distinguishes itself from sibling tools by explicitly pairing with '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?

The description explicitly states when to use this tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions the complementary tools 'remember' and 'recall', guiding the agent on 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?

Description reveals behavioral details beyond annotations: fetches the page, extracts title/description/links, emits standard markdown format. Annotations (readOnly, idempotent, non-destructive) align with this, and no contradictions exist.

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?

Compact two-sentence description with front-loaded purpose. Every sentence contributes meaningfully 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?

Given the simple inputs (url, optional max_links) and clear output (text blob), the description fully explains what the tool does, how it works, and typical use cases. No output schema needed.

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 completely (100% coverage). Description adds value by specifying default (25) and maximum (50) for 'max_links', which is not in the schema, and reinforces 'url' purpose.

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 generates a llms.txt file for any URL, with specific verb 'generate' and resource 'llms.txt'. Includes concrete use cases and output format, making it distinct from any sibling 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 lists three use cases (client indexing, own project, auditing competitor), providing clear context for when to use the tool. No alternative or exclusion guidance is needed given the tool's uniqueness.

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. Description adds that it returns specific fields (id, type, params, etc.) and focuses on active subscriptions, providing useful 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 that are front-loaded with the core purpose and efficient in conveying all necessary information without waste.

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

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

Despite no output schema, the description lists return fields and behaviors. Combined with rich annotations and low complexity (one optional param), it is sufficiently complete for an AI 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 a clear description for the only parameter 'include_inactive'. Description does not add extra parameter 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 verb 'List', the resource 'subscriptions', and the scope 'caller's active subscriptions', making it distinguishable from sibling tools like subscribe/unsubscribe.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. Does not explicitly exclude other uses or mention 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 only provide all-false hints, so the description carries the full burden — and it delivers: discloses the rate limit (5 per identifier per day), the no-quota-count policy, the claim_token lifecycle (filing returns a token; passing it back later reads resolution status), the daily human review cadence, and roadmap impact. 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?

At ~170 words it is long, but every sentence carries distinct functional information: purpose, categories, exclusions, content rules, token flow, review cadence, rate limit, quota. It is front-loaded with the core purpose and organized logically from purpose to mechanics; only slightly longer than strictly necessary for a simple feedback 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?

With no output schema, the description properly explains the return behavior (claim_token on filing, status read-back on later call). It covers routing exclusions, rate limiting, cost/quota, content expectations, and the daily review SLA. Combined with 100% schema parameter coverage and a clear sibling distinction, nothing material is left to discovery.

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

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

Schema coverage is 100%, so parameters are already well-documented (enum meanings, context fields, max chars). The description adds real value on top by explaining the claim_token's origin ('Filing without an account returns a claim_token'), the two-step claim workflow, and tying the context guidance ('Describe the issue in terms of Pipeworx tools/packs') to the structured context object.

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 specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates the exact feedback categories (bug, feature, data_gap, praise). It clearly scopes the tool to Pipeworx-served tools only, which distinguishes it from any sibling tool.

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 guidance per category: '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 gives a clear exclusion: tools from a different MCP server should be filed with that server instead, plus content rules (describe in terms of Pipeworx tools, don't paste end-user prompts).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds that data is self-aggregating from 'CF analytics-engine', no PII is tracked, and caching varies by window (5min-1h), 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?

The description is concise (three sentences plus a bullet list of uses), well-structured with front-loaded action and 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?

While the description covers parameter and behavioral aspects well, it does not describe the return format (e.g., structure of top tools/packs). Given the lack of output schema, this omission leaves agents uncertain about the response shape.

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 descriptive enum values. The description adds value by explaining the semantic difference between windows: shorter for hot trends, longer for steady-state demand, which aids parameter selection.

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 configurable windows, distinctly different from sibling tools like 'ask_pipeworx' or '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?

Three explicit use cases are provided (discovering hot data, confirming canonical tool, aligning use case) offering strong context. However, it does not explicitly mention when not to use the tool or contrast with 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 declare readOnly and non-destructive. Description adds detailed context: scanning behavior, similarity filter, placeholder filter, fill check logic, and that realizable edge ≤ 0 means no trade. No contradictions.

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

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

Well-structured with clear sections, but verbose with technical details. Every sentence adds value, though could be trimmed for brevity. Front-loaded with 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?

No output schema, but description details response structure (opportunities[], partition_check, fill_check) and covers all modes, edge cases, and filtering logic. 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. Description adds examples (event slugs, seed questions), explains mode differences, and provides guidance on which parameter to use and when.

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 via monotonicity violations and partition-sum checks, and distinguishes between three modes (no args, event, topic) with specific behavior for each.

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 each mode: trending scan for top markets, event for specific market (recommended), topic for cross-event scanning. Also warns about fill check and references sibling tool for custom sizing.

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

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

The description extensively covers behavioral traits beyond annotations: caching behavior (1h KV cache), model families, response structure with diagnostics, and exclusion of Fed bets. This adds significant context not available in 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 with clear sections and explanations. Every sentence adds value, though it could be shortened without losing 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?

Without an output schema, the description fully compensates by detailing the response structure (by_segment, diagnostics), edge cases (Fed bets, empty segments), and knob effects. It is remarkably 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?

All 9 parameters have schema descriptions, but the tool description adds substantial meaning: e.g., explaining default slippage rationale, half-Kelly interpretation, and tradeable-edge filter effects. This goes well 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's purpose: scanning top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It clearly conveys the intended use case ('what should I bet on today') and distinguishes from siblings by focusing on top markets without paging.

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

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

The description explains when to use the tool (for discovering opportunities) and provides detailed guidance on tradeable-edge knobs and how to set them. However, it does not explicitly state when not to use it or name alternative tools, slightly reducing clarity.

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

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

Annotations declare read-only, idempotent, non-destructive. The description adds value by detailing output structure (tracked[], expired[], snapshot_dates[]) and limitations (60-day TTL, decay from daily closes). No contradictions.

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

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

The description is dense but well-structured, front-loaded with purpose. Every sentence adds value, though it is slightly verbose.

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

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

Without an output schema, the description thoroughly explains return fields (tracked, expired, snapshot_dates) and constraints (TTL, decay computation), making it complete for agent 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 reiterates default/clamp values for 'days' and default for 'window'. It adds no significant new meaning beyond the schema.

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

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

The description clearly states the tool tracks 'edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?'. It distinguishes 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 explains the purpose and context (fresh wide edge vs 3-week-old), but does not explicitly state when not to use or name alternatives. It implies usage for historical edge analysis.

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

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

The description adds behavioral details beyond annotations (readOnlyHint, etc.), such as walking the ladder, returning specific fields (vwap_fill_price, slippage_pp, etc.), and warning about partial basket fills leading to directional 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?

The description is long but well-structured, with front-loaded purpose and clear separation of modes. While every sentence adds value, the length might be reduced slightly without losing information. However, it remains effective.

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

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

Given the complexity (two modes, multiple outputs, no output schema), the description is thorough: it lists return fields for both modes, mentions thin legs, forced directional risk, and default/clamp values. No gaps in essential information.

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 contextual meaning: explains size_usd interpretation for both modes, side defaults and auto-detection for basket, and clarifies the meaning of parameters in the context of use. This goes beyond the schema alone.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and explains both single-market and basket modes. It distinguishes itself from sibling tools by specifying when to use it (before acting on arb signals or edges trades above ~$500).

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 the tool (before arb signals or edges trades above ~$500), why (theoretical overround on thin books is not capturable, partial basket fills cause unhedged positions), and what is required (one of market or event). Provides clear context for usage and alternatives.

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

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

Discloses safety fields (compatibility_warning, temporal_alignment, skipped_cross counters) that explain when spreads are meaningful, adding significant behavioral context beyond the read-only, idempotent 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?

Well-structured with headers (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Some redundancy but overall informative without being excessively verbose.

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

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

Despite lacking an output schema, the description thoroughly explains response structure and safety warnings, providing sufficient context for a complex cross-venue 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%, providing baseline. Description adds value by detailing the two modes, listing valid topic values, and explaining overrides, facilitating correct invocation.

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

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

Description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

Explains two usage modes (pre-mapped topics vs explicit tickers) and cautions that most pre-mapped topics return compatibility warnings, guiding appropriate use. Lacks explicit comparison to sibling tools but implicitly differentiates.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' This clarifies data isolation without contradicting 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: first gives core action and variation, second gives use cases and technical context. Every sentence carries essential information with no 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?

For a simple tool (1 optional parameter, no output schema, complete annotations), the description covers retrieval, listing, scoping, and pairing with siblings. No gaps remain given the tool's complexity.

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

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

Schema coverage is 100% with one optional 'key' parameter described as 'Memory key to retrieve (omit to list all keys).' The description reinforces this by stating 'omit the key argument' and explains the effect of omission (list all keys), adding slight extra value over the schema.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the verb (retrieve/list) and resource (saved memory), and distinguishes itself from siblings like 'remember' and 'forget' by naming them explicitly.

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: 'Use to 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 contrasts with alternatives: 'Pair with remember to save, forget to delete,' guiding when to use each 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?

Discloses return fields (source, citation_uri, payload), filtering options, and the mark_read behavior which affects subsequent calls. Annotations already indicate idempotent and read-only, and the description adds valuable behavioral context.

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

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

Concise yet comprehensive paragraph. Front-loaded with purpose, no wasted words. 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?

Covers all parameters, explains return fields, gives polling advice, and mentions an alternative endpoint. No gaps given the tool's complexity and available 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?

Adds meaning beyond the schema by giving examples (e.g., 'sec_8k' for type), explaining mark_read's effect, and clarifying limit range. Schema coverage is 100% but description enhances usability.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', explaining what it returns. It distinguishes from sibling tools like list_subscriptions by focusing on events/alerts.

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

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

Provides guidance on polling and alternative access via URL. However, it does not explicitly contrast with sibling tools for when to use this versus others.

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

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

Annotations already mark it as read-only and idempotent. The description adds details about data source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail), return format (grouped changes[], total_changes, citation URIs), and parameter specifics. 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 somewhat lengthy but well-structured: example queries first, then operation summary, data sources, parameter details, and alternative tool. All sentences add value, though slight trimming could improve conciseness.

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

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

Given the tool's complexity (multiple data sources, fallback logic, soft-fail) and no output schema, the description covers behavior comprehensively: return format, parameter formats, source-specific notes, and an alternative tool for static profiles. It leaves no major 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 covers all parameters (100% coverage), but the description adds value by providing concrete examples for 'since' (ISO date and relative shorthand, with a monitoring suggestion), examples for 'value' (ticker or CIK), and clarifying that 'type' only supports 'company'. 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 starts with concrete example queries and states 'change feed for a company in the last N days/weeks/months in ONE parallel call', clearly specifying verb, resource, and scope. It lists data sources and explicitly distinguishes from sibling tool entity_profile, earning a top score.

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 entity_profile for static profiles, providing a clear alternative for a different use case. While it doesn't exhaustively list when not to use the tool, the guidance is direct and helpful for an AI 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?

Adds key details beyond annotations: key-value scoping by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradiction with annotations (idempotentHint=true, readOnlyHint=false).

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 value, but slightly verbose (e.g., '— across this conversation or across sessions' could be streamlined). Still efficient overall.

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 save tool: covers scope, persistence, usage pairing, and example scenarios. No return output needed.

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 has 100% coverage with clear descriptions; description reinforces with examples (key: 'subject_property', value: 'findings'). Adds no contradictions.

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 saves data for reuse across conversations/sessions, with concrete examples (resolved ticker, user preference). Distinguishes from sibling tools 'recall' and 'forget'.

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

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

Explicitly specifies when to use (discover something worth carrying forward) and pairs with recall/forget. Also clarifies behavior differences for authenticated vs anonymous users.

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

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

The description discloses significant behavioral traits beyond annotations: it cascades through multiple endpoints, degrades gracefully if LEI/FIGI sources are unavailable, explicitly reports unresolved identifiers, and labels each identifier with its source. This is far more than the annotations alone convey.

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

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

The description is long but well-structured and front-loaded with examples. Every sentence adds value, though the list of example phrasings is somewhat redundant. It balances detail with readability, making it appropriately sized for the tool's complexity.

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

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

Given the tool handles two entity types, multiple identifiers, and external data sources, the description covers all essential aspects: input formats, output components, fallback behavior, and the lack of an output schema is compensated by detailing return fields and the 'unresolved' array. This is comprehensive 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?

While schema coverage is 100%, the description adds rich meaning by elaborating on the 'type' parameter's accepted values and what each returns (CIK/ticker/LEI/FIGI for company; RxCUI/brand for drug). It also clarifies the 'value' parameter with concrete examples like 'AAPL' and 'ozempic', going well beyond the schema's brief 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 resolves names to canonical identifiers, with a specific verb ('resolve') and resource (identifiers). It lists concrete example queries and explicitly distinguishes itself from siblings by stating 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and outlines supported types and input formats. However, it does not name alternative tools or provide when-not-to-use conditions, so it falls short of a 5.

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

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

Beyond annotations (readOnly, idempotent, openWorld), description reveals it probes each entity with ai_visibility_check, ranks by score, and treats first entity as subject. 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, front-loaded with core function, each sentence adds value (purpose, use case, output). 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?

Fully documented parameters (100% coverage), good annotations, description includes return fields (ranked list, score, confidence, signal density). No output schema needed.

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 4 parameters with descriptions. Description adds meaning: first entity is subject, context disambiguates, probes each entity. Provides richer usage 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?

Description clearly states 'Compare AI visibility across multiple entities side-by-side,' with specific verb (compare), resource (AI visibility), and outcome (ranked list). Distinguishes from sibling 'ai_visibility_check' by emphasizing multi-entity comparison.

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

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

Explicitly positions tool for competitive AI-marketing audits and gives an example question. Does not list exclusions but context with siblings makes usage scope 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?

Description adds significant behavioral context beyond annotations: fans out to multiple services, explains return structure (summary block, advisories, links, alternatives), mentions potential delay of 5-30s on bundlephobia first measurement, and graceful degradation via sources_failed. 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 verbose. Every sentence adds value, but it could be more structured. Front-loaded with the key purpose. Minor deduction for unnecessary words like 'Composite... check'.

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

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

Given no output schema, the description fully explains the return value: fields in summary block, per-advisory detail, links, and alternative versions. Also covers partial failures and ecosystem limitations. 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 coverage is 100%, so baseline is 3. Description does not add meaning beyond what the schema provides: it repeats that package is npm name with scoped support and version defaults to latest. No extra 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?

Description clearly states the tool is a composite check for npm packages to answer 'should I add this package?' by combining deps.dev and bundlephobia data. It uses a specific verb and resource, and is distinct from sibling 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 tells when to use: when an agent asks about safety, popularity, size, or cost of an npm package. Also tells when not to use: only npm ecosystem in v1, and mentions alternatives for other ecosystems (deps.dev:version 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 indicate read-only, idempotent, non-destructive behavior. The description adds implementation details (BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag) and output format (passages with offsets and scores), which exceed what annotations provide.

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

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

The description is a dense paragraph that front-loads purpose and usage, then adds behavioral details. Every sentence contributes unique information, but it could be slightly more structured (e.g., bullet points for constraints). Still concise given the amount of useful information.

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

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

Despite lacking an output schema, the description specifies return values (passages, offsets, scores), constraints (200K char cap, truncation flag), and integration with a sibling tool. This is complete for a tool with 3 parameters and 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%, so baseline is 3. The description adds value by providing examples for the query parameter ('supply-chain risk', 'fiscal year 2024 revenue') and clarifies default limit (5) and max text size, but does not significantly extend beyond schema descriptions.

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

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

The description clearly states the verb ('semantic search') and resource ('inside a fetched record'). It distinguishes from siblings by focusing on searching within an already-fetched text, contrasting with tools like ask_pipeworx_grounded that ground over passages.

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

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

Explicitly tells when to use: 'when the record is too big to cram into the prompt'. Provides an alternative ('Pairs with ask_pipeworx_grounded') and explains how it saves context and returns only relevant passages.

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 non-read-only, idempotent, non-destructive. The description adds behavioral details: requires authentication, rate limits (SMS 10/day), webhook auto-disable after 10 failures, one-time signing secret. 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 lengthy but well-organized, with the core purpose front-loaded. Each sentence provides valuable information, though the density might be slightly overwhelming. It earns a high score for efficiency given 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 (multiple subscription types, delivery channels), the description covers parameter semantics, behavioral notes, and prerequisites thoroughly. The absence of an output schema is partially mitigated by the explicit mention of returning a subscription ID. It is complete enough for practical 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%, but the description adds substantial value beyond the schema. It explains each subscription type's parameter structure with examples (e.g., sec_8k items for officer changes, polymarket_edge topic and min_spread_bps, fred_series series_id), and details delivery channel semantics including verification and rate limits.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream. It uses a specific verb ('create') and resource ('subscription'), and provides concrete examples of subscription types and delivery channels, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

The description specifies when to use the tool and prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist). It details different subscription types and delivery options, but does not explicitly contrast with alternatives like recent_alerts or other monitoring 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 readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: it returns example questions with exact tool+argument shapes, and explains the effect of omitting vs. providing the topic argument.

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

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

The description is somewhat lengthy but front-loaded with purpose. Each sentence adds value, but could be slightly more concise without losing meaning.

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

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

For a discovery tool with one optional parameter and no output schema, the description fully covers what the tool does, how to use it, and what kind of output to expect.

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

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

Schema coverage is 100%, baseline 3. Description adds context about the topic parameter by listing example values and explaining that omission gives full spread, which goes beyond the schema 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 uses specific verbs and nouns: 'returns category-bucketed example questions' and clearly states it is the 'onboarding entry point'. It distinguishes itself from siblings like ask_pipeworx by focusing on discovery rather than direct answering.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains when to use the topic parameter. Does not explicitly mention when not to use it, but the guidance 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?

Discloses deactivation vs deletion and references recent_alerts for history. Complements annotations (destructiveHint=false, idempotentHint=true) without contradiction.

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

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

Two sentences, front-loaded with action, immediately followed by key constraints and effects. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, constraint, behavior, and links to related tool. Fully adequate.

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% already describes the 'id' parameter. Description adds no additional semantic value beyond restating 'by id'.

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

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

The description uses specific verb 'Cancel' with resource 'subscription by id', clearly distinguishing it from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement and mentions that historical events remain available via recent_alerts, providing context. However, does not explicitly state when not to use or compare to 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?

With annotations already declaring read-only, open-world, and idempotent behavior, the description adds significant value by explaining subtle output distinctions: 'could_not_verify' means the check didn't happen and must not be used as evidence, while 'unsupported' means no source exists. It also discloses the routing logic and the fact that it returns citations. This goes well beyond what annotations provide.

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

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

The description is long but every sentence carries essential information. It opens with query examples, then explains routing, return values, and critical caveats about error states. No word is wasted; it is structured logically and front-loads the tool's 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?

There is no output schema, so the description must explain return values—and it does thoroughly, listing all verdicts and clarifying the meaning of each. It covers error conditions, citation format, and the two processing paths. With only 2 parameters (both well-covered), the description provides a complete picture for correct invocation and interpretation.

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

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

Schema coverage is 100% for both parameters, so the schema already explains them well. The description adds extra meaning by clarifying that tolerance_pct overrides the wording-implied tolerance and is useful for hallucination detection (1–2%). This is a valuable addition, so the score is above baseline.

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

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

The description clearly identifies the tool as a claim verifier with specific verbs ('fact check', 'verify', 'confirm or refute') and specifies the resource (authoritative sources). It distinguishes itself from sibling tools by describing its role as a replacement for a multi-step pipeline (NL parsing → entity resolution → data lookup → comparison), making its 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 states when to use it: 'whenever the agent needs to check whether something a user said is factually correct.' It also provides context about the two paths (sec EDGAR for company-financial claims vs. grounded pipeline for others). It doesn't explicitly say when not to use it or name alternative tools, but the guidance is strong enough to guide selection.

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