Travel Feeds

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context: cost implications (free default, BYO key for Anthropic), default model details, and expected return structure (score, confidence, signals, raw_response). No contradictions with annotations.

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

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

The description is two sentences: the first covers core functionality and output format, the second adds model/pricing details. Every word serves a purpose, and it is front-loaded with the primary action. No redundancy or fluff.

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

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

Despite no output schema, the description explicitly lists the per-model return fields (score, confidence, signals, raw_response) and a combined view. Combined with annotations covering safety and idempotency, the description is complete for an agent to understand how to invoke and interpret results.

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

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

All four parameters are described in the schema (100% coverage). The description enhances understanding by explaining the default model for 'models', the purpose of '_apiKey' (BYO key, direct billing), and disambiguation role of 'context'. This adds actionable guidance beyond the schema.

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

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

The description clearly states the tool's purpose: probing LLMs to measure visibility (0-100) for entities. It specifies the verb 'probe', the resource 'LLMs', and the business use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). This differentiates it from sibling tools like 'scan_competitor_ai_presence' which might have a narrower 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 provides clear context on when to use (AI-marketing audits, brand checks) and how to optionally include Anthropic with a key. However, it does not explicitly state when not to use or list alternatives among the 40+ sibling tools, leaving room for improvement.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond that: it routes to 5,798 tools across 1,517 sources, automatically fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. This gives the agent a clear mental model of the tool's internal behavior and output style, exceeding what the annotations alone 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 core guidance is front-loaded and valuable, but the middle is padded with redundant hype: 'for everyone, on every plan, day one, default, preferred, direct, optimal, best first move' adds no information. The list of alternatives is useful but the capitalized rhetorical emphasis ('START HERE for most questions') and repetitive phrasing make the description longer than needed. Clear-but-wasteful earns a 2.

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

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

For a single-required-parameter router tool with no output schema, the description is remarkably complete: it names the input type, gives diverse domain examples, states the return format (structured answer with citation URIs), and covers exclusions/alternatives. An agent has everything it needs to decide when to invoke this tool and what to pass.

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

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

Schema description coverage is 100%, and the question parameter's description already documents natural-language input and its six aliases. The description adds example queries that illustrate expected phrasing, but it does not supply additional parameter-level semantics beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 strong directive: 'PREFER OVER WEB SEARCH for questions about current or historical data' and then enumerates specific domains (SEC filings, FDA data, economic statistics, patents, real estate, etc.). It clearly states the tool's function: 'Routes the question to the right one of 5,798 tools... returns the structured answer with stable pipeworx:// citation URIs.' This is a specific verb+resource+scope statement that distinguishes it from web search and, through the sibling list, from other ask_pipeworx variants.

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

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

The description explicitly tells the agent when to use this tool ('Use whenever the user asks...') and provides concrete example queries. It also gives clear alternatives: ask_general for low-latency, ask_pipeworx_agentic for the agentic version, ask_pipeworx_lite for a lighter answer, deep_research for policy analysis, and ask_pipeworx_grounded for citation-grounded guarantees. This is textbook when-to-use vs alternatives guidance.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the experimental nature, live candidate routing, current inactive state, and that it is a full working router with no fallback. This adds valuable behavioral context that annotations alone do not 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 concise and front-loaded, with the beta status and relationship to ask_pipeworx stated immediately. Each sentence adds useful context, though minor repetition exists around 'identical' and 'same ... same ... same'.

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 states that the response shape is identical to ask_pipeworx, which fully answers what to expect. It also covers current state, routing behavior, and usage context, leaving no critical gaps for an agent to call it correctly.

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

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

Schema description coverage is 100% and the description adds no new parameter-level meaning beyond confirming they match ask_pipeworx. With all parameters being aliases for 'question', the schema already fully documents them.

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 this as the beta variant of ask_pipeworx, a universal router, and distinguishes it from the stable version by its experimental routing improvements. This positions it precisely among siblings like ask_pipeworx and ask_pipeworx_grounded.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, giving clear context for when to choose it. It does not explicitly list exclusions or alternatives, but the naming of ask_pipeworx and the 'newest routing' condition is sufficient 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 read-only, idempotent, open-world, and non-destructive behavior, and the description enriches this with the grounded extraction guarantee, explicit refusal reasons, and the extra LLM call cost. It clearly discloses that the tool may return a refusal rather than an answer when evidence is insufficient. No contradiction with annotations exists.

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 every sentence earns its place: it states the behavior, return shape, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the most important defining trait, hallucination resistance, and then provides structured detail. The length is justified by the tool's complexity and high-stakes context.

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

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

For a tool with no output schema, the description fully compensates by specifying the exact success response fields and the refusal_reason enum values. It also covers routing behavior, cost, and when to prefer the alternative, making it complete for an agent to decide and call correctly. There are no significant gaps in context.

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

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

Schema coverage is 100% and the schema fully documents the single question parameter and its aliases, so the baseline is 3. The description adds useful context beyond the schema by explaining that the question is routed to an underlying tool that fills arguments from 5,798 tools across 1,517 sources. This clarifies that the user question is high-level rather than a direct function call.

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 this is a hallucination-resistant answer mode that routes like ask_pipeworx, fetches data, and extracts answers only from tool results. It immediately differentiates itself from ask_pipeworx by emphasizing grounded, evidence-backed answers for high-stakes reads. The verb and resource are specific and the purpose is 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 says to use this tool whenever an answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete examples like financial verdicts and legal claims. It also names the alternative, ask_pipeworx, and instructs to prefer it for casual lookups. This makes the selection decision unambiguous.

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 idempotent, read-only, non-destructive. The description adds extensive behavioral detail: market resolution, classification, fan-out, response shapes, low-confidence handling, closed market behavior, spread warnings, and cancellation rule parsing. 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 very long (~800 words) with dense detail. While structured into sections, it burdens the agent with excessive information that could be deferred to docs or structured outputs.

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 3 parameters, no output schema, and complex behavior, the description thoroughly covers all necessary aspects: input formats, response shapes, edge cases, safety guards, and resolution rules. An agent can reliably invoke and interpret results.

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

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

Schema covers all parameters (100%). The description adds examples for market, explains depth (quick vs thorough), and include_raw (summarized vs full). This adds value beyond the schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific use cases like 'should I bet on X'. It distinguishes from siblings such as polymarket_edges which is for edge tracking.

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 (for bet research, data questions). It includes usage tips like inspecting resolver contract, but does not explicitly list when not to use or compare 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds critical behavioral context: for type='company', it pulls latest 10-K data from SEC EDGAR/XBRL with correct fiscal year handling; for type='drug', it pulls FAERS counts. It also mentions results are sorted by primary metric and returns paired data with pipeworx:// citation URIs. 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 highly concise (under 800 characters) and front-loaded with the purpose and trigger phrases. Every sentence adds value: use case, data sources, sorting, citations, and efficiency claim. No redundant or filler content.

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

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

Given the tool has no output schema, the description adequately covers what is returned (paired data + URIs) and how results are sorted. It mentions data sources and entity types. A minor gap is not explicitly stating that the tool is read-only, but annotations already cover that. Overall, it provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining what each type returns (company: revenue, net income, cash, debt; drug: adverse-event counts, FDA approvals, trials) and gives concrete examples for the values parameter (tickers/CIKs for company, drug names for drug). This provides meaningful context beyond the schema's type and array 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 performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It uses specific verb phrases like 'Compare X and Y', 'rank these companies', and 'head to head', and distinguishes from siblings such as entity_profile by emphasizing it is preferable over sequential 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 explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear directive for when to use this tool. It also lists trigger examples like 'which is bigger / better / larger / more profitable' and notes it replaces 8-15 sequential lookups, guiding the agent to prefer this over multiple entity_profile calls.

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

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

The description is exceptionally transparent about behavior: it is grounded, not open-web search, decomposes questions, routes to tools in parallel, returns explicit gaps rather than inventing findings, includes contradictions for certain depths, and explains how citations are guaranteed fetchable. It also discloses latency expectations and the excerpting of large records. This far exceeds what 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 information-dense, with almost every sentence contributing a distinct behavioral or routing fact. It is front-loaded with the account requirement and the alternative tool. It loses a point because the single-paragraph presentation and heavy use of parenthetical asides make it harder to skim, but it is not padded.

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

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

Given that there is no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: findings include verbatim evidence, confidence, source, fetched_at, and a stable citation_uri, plus gaps[] and contradictions[] where applicable. It also covers timing, prerequisites, and behavior differences across depth levels. Nothing essential for calling the tool correctly is missing.

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 the two parameters, so the baseline is 3. The description adds meaningful value by explicitly connecting depths to behavior ('thorough' requires a paid plan, standard/thorough add gap recovery and contradictions, thorough adds iterative lead-chasing) and by clarifying that the question parameter accepts broad natural language. This is more than a restatement of 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 grounded multi-source research capability over Pipeworx's structured data sources and distinguishes it from open-web search and from ask_pipeworx. It names the resource, the action (decomposes and routes research facets), and the deliverable (findings packet with citations and gaps). No ambiguity remains about what the tool does.

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

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

The description explicitly states when to use deep_research: broad/multi-part questions over structured data. It also gives precise when-not-to-use guidance: single lookups should use ask_pipeworx, and users who are not signed in should use ask_pipeworx instead. It additionally names the paid requirement for the 'thorough' depth, making routing decisions concrete.

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 show readOnlyHint and idempotentHint. The description adds that it returns names, descriptions, and full input schemas with curated examples, each result ready to call directly. It also mentions default limit (20) and max (50). 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 concise yet information-dense: front-loaded purpose, followed by examples, return value explanation, and usage guidance. No unnecessary words.

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

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

With 6 parameters (1 required) and no output schema, the description covers what the tool does, how to use it (natural language query), what it returns (names, descriptions, schemas with examples), and when to call it. No gaps remain.

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

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

Schema coverage is 100%, so baseline 3. The description explains that 'query' accepts natural language and lists multiple aliases (q, task, search, description) with examples. This adds value beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples like SEC filings, FDA drugs, and housing markets, and distinguishes itself from siblings by noting it returns top-N tools with full schemas, ready to call.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells when to use it and contrasts with other tools that might provide one answer instead of browsing.

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 readOnly/idempotent hints, the description discloses fan-out across eight source categories, return field semantics, soft-failure for USPTO, that empty sections mean real 'no data', private-company resolved:false behavior, and interchangeable type handling. This gives the agent an unusually complete picture of the tool's runtime behavior.

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

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

The description is long, but it is front-loaded with trigger examples and the core one-call promise, then organized into source coverage, return fields, input formats, and edge cases. Nearly every sentence adds behavioral or selection-relevant information; only minor redundancy exists around the type/value interchangeability.

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 carries the full burden of explaining return values, and it does so thoroughly: it lists every response section, defines failure/no-data semantics, explains what to expect for companies lacking certain data types, and clarifies supported input forms. For a complex multi-source tool, this is complete enough for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: it specifies that type and value are interchangeable, that value can be a ticker, zero-padded CIK, or name, and how ambiguous/non-public values resolve. These details go beyond the schema's already good 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 states a highly specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It includes concrete trigger phrases, and it explicitly contrasts itself with chaining single-pack SEC/XBRL/news lookups, making the tool's identity and scope 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?

It gives an explicit usage rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It clearly describes when to use this tool, though it does not directly address when a sibling like compare_entities or deep_research might be more appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds value by detailing CF-robust behavior: direct fetch with proxy fallback if blocked. This goes 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 with no waste. First sentence is the clear purpose, second provides behavioral and usage context. Perfectly front-loaded and concise.

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

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

No output schema, but description mentions normalization hinting at structured output. Explains fallback behavior and provides usage tip. Missing return format, but overall sufficient for a simple fetch tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds no additional parameter semantics beyond what the schema provides, so baseline of 3 is appropriate.

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

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

Description clearly states verb 'fetch and normalize' and resource 'any RSS/Atom/RDF feed by URL'. It distinguishes from sibling 'list_feeds' by advising to use that first for curated sources.

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 list_feeds first for curated sources', providing clear context for when to use an alternative. However, no explicit when-not to use this tool is given.

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

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

Description aligns with annotations (destructiveHint=true, idempotentHint=true). It adds no contradictions; the destructive nature is clear. Could mention permanence but annotations already cover it.

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 purpose, followed by usage guidance and related tools. No redundancy, every sentence adds value.

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

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

For a simple delete tool with one required param, description covers purpose, usage context, and sibling relationships. 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?

Single parameter 'key' with schema description 'Memory key to delete.' 100% schema coverage; description does not add extra param details 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 'Delete a previously stored memory by key,' providing a specific verb (delete) and resource (memory by key). It distinguishes from sibling tools like remember and recall.

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

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

Explicitly states when to use: 'when context is stale, task is done, or you want to clear sensitive data.' References sibling tools remember and recall as 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 discloses the fetch-extract-emit process, output format (single text blob), and deployment location, adding behavioral detail beyond the annotations (readOnlyHint, idempotentHint). 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?

Description is two sentences: first defines purpose and output, second lists use cases. No unnecessary words, front-loaded with key information, and easy to parse.

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 2 parameters, rich annotations, and no output schema, the description fully covers what the tool does, how it works, and its output. No missing critical 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?

Input schema covers both parameters (url, max_links) with descriptions, achieving 100% coverage. The description repeats schema info (default 25, max 50) without adding new semantic meaning, 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?

Description clearly states the tool generates a production-ready llms.txt file for a given URL, specifying the action, resource, and purpose (AI crawler indexing). It is distinct from sibling tools like deep_research or scan_competitor_ai_presence.

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

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

Description provides explicit use cases (client site indexing, personal project drafting, competitor auditing), guiding when to use the tool. It does not explicitly contrast with siblings but gives sufficient context for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's marginal addition of listing fields and optional filtering does not reveal new behavioral traits. The description is consistent with annotations but not additive beyond filtering details.

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

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

Two concise sentences with no wasted words. The main action and key differentiating point are front-loaded, making it easy for an agent to quickly grasp 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?

For a low-complexity tool with two optional params and no output schema, the description covers the core functionality and links to an alternative tool. Minor gaps like pagination or sorting are not critical given the simplicity.

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

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

Schema description coverage is 100%, with both parameters fully described. The description restates that filtering by category or keyword is optional, adding no new meaning beyond the schema's existing documentation.

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

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

The description clearly states the tool lists curated travel feeds with specific fields (id, title, category, source). It distinguishes from the sibling 'read_feed' by directing to pass an id to fetch a full feed, providing clear differentiation.

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

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

The description explains optional filtering by category or keyword, and indicates that to retrieve a specific feed, one should use 'read_feed'. It does not explicitly state when not to use this tool, but the context for browsing vs fetching is clear.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat safety. It adds value by detailing what fields are returned and noting the default active-only filtering, but doesn't mention potential pagination limits.

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

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

Two sentences, front-loaded with the core purpose, then return fields, then usage guidance. Every sentence earns its place with zero wasted words.

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

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

The description covers the tool's purpose, return fields, default behavior, and use cases. For a simple list tool with one optional parameter, this is complete. The lack of pagination mention is minor given the tool's nature.

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 parameter is already well-documented. The description adds context that the tool only shows active subscriptions by default, which aligns with the include_inactive parameter. No redundant explanation.

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 lists the caller's active subscriptions and specifies the exact fields returned (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear guidance on when to use this tool versus alternatives like subscribe or unsubscribe.

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

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

Discloses several behavioral traits not captured by annotations: rate-limiting ('5 per identifier per day'), no cost ('doesn't count against your tool-call quota'), the claim_token flow for anonymous filing and later follow-up, and the daily digest/review process. Also instructs users not to paste end-user prompts, a subtle but important usage constraint.

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 every sentence adds value—no filler. However, it's a single wall of text that could benefit from light structure (e.g., bullets) for easier scanning. Length is justified given the tool's purpose and the nuance required.

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 and sparse annotations, the description fully explains the whole lifecycle: what to report, when not to report, how to file, what to expect back (claim_token), and how to follow up later. It also mentions rate limits, cost, and the product impact, making the tool's behavior completely predictable 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 already covers all 4 parameters with descriptions, but the description adds pragmatic meaning: it explains how claim_token is used ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and that it should be used with no other arguments, going beyond the schema's basic 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 opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly covers bug, feature, data_gap, and praise categories, and distinguishes this feedback tool from the many research/prediction siblings by limiting scope to tools served by this Pipeworx connection.

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 scenarios with concrete examples ('wrong/stale data (bug)', 'tool you wish existed isn't in the catalog (feature/data_gap)', 'worked surprisingly well (praise)'). It also gives a clear exclusion: feedback about tools from a different MCP server should be filed there, not here, and clarifies how to identify Pipeworx 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds crucial behavioral context: data is self-aggregating from CF analytics, no PII, cached 5min-1h. No contradiction with annotations.

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

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

The description is concise (two paragraphs) with no wasted words. Each sentence provides essential information: purpose, use cases, data source, caching policy. Well-structured and front-loaded.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description sufficiently explains what is returned (top tools, packs, volume) and the data source. Could mention whether results are ordered or any limits, but overall complete for its complexity.

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

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

Schema coverage is 100% with a single parameter (window) that has a description and enum. The description adds value by explaining the trade-off between windows (short for hot, long for steady-state), which enhances understanding beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a time window. It uses specific verbs ('Returns') and distinguishes from siblings like 'ask_pipeworx' or 'discover_tools' by focusing on trending data.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tool, aligning use case) and explains when to use different window lengths. This provides excellent guidance on when to invoke this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds valuable context about fill checks, semantic anchors, partition filters, and when not to trade (realizable_edge_pp ≤ 0). 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-structured with clear sections. Each sentence adds value; no fluff. Could be slightly more concise, but the complexity of the tool justifies the 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?

The description covers the response format (opportunities[], partition_check), fill check, and custom sizing. Despite no output schema, it gives enough detail for an agent to use the tool correctly. Completes the picture for both modes.

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?

Both parameters have schema descriptions, and the tool description provides extensive context: how event slugs work, how topic triggers cross-event search, internal logic like Jaccard similarity and placeholder filters. Adds significant 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 states clearly that the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between two modes (event, topic) and a arg-less trending_scan, differentiating it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly advises when to use each mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It explains the rationale for cross-event mode and mentions alternatives like polymarket_fill_risk for custom sizing. Clear guidance on when and how to invoke.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context including caching (1h at KV level keyed on all knobs), detailed model families, output structure, and diagnostic information. No contradictions with annotations.

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

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

The description is well-structured with clear sections: purpose, model families, response fields, knobs, and caching. It is verbose given the complexity, but each sentence adds value. Some details could be in the schema or separate documentation, so not a perfect 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?

With 9 parameters and no output schema, the description comprehensively covers the output structure (by_segment, fed_candidates, diagnostics), caching behavior, model details, edge calculations, and tradeable-edge filters. No gaps remain for an agent to understand how to use the tool correctly.

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

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

Schema coverage is 100% with each parameter described. The description adds meaningful context beyond the schema, such as explaining slippage assumptions ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade') and usage guidance for knobs like min_partition_leg_kelly. This elevates it above the baseline of 3.

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

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

The description clearly states the verb 'Scan' and 'return' with the resource 'top Polymarket markets', specifying the core function of finding opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools like polymarket_arbitrage by focusing on model-driven and structural opportunities.

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 the tool is built for 'what should I bet on today' and explains how agents discover opportunities. It provides context on when to use it, but does not explicitly contrast with alternatives or state when not to use it, which would elevate it to a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the tool is non-destructive. The description adds significant behavioral context: response structure (tracked, expired, snapshot_dates), trend and decay calculations, limits (60-day TTL, intraday exclusion), and meaning of negative values. 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 lengthy but well-organized, front-loading the core question and response details. Every sentence adds value, though some consolidation could improve conciseness. The structure with labeled fields helps readability.

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

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

With no output schema, the description comprehensively documents the response fields, their meanings, trend computation, and limitations (60-day TTL, snapshot gaps). It fully equips the agent to interpret results correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context by explaining default values (days=14, window='1wk'), maximum days (30), and the meaning of the window parameter (snapshot family). This provides additional semantic clarity 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 provides edge persistence and decay telemetry from daily snapshots, answering a specific question. It distinguishes itself from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage (arbitrage opportunities).

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 context ('how long has this edge existed and is it shrinking?') and when to use it, but does not explicitly mention when not to use it or provide alternative tool names. However, the purpose and response structure imply appropriate usage scenarios.

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

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

Annotations indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it explains the ladder-walking process, return fields (top_of_book, vwap_fill_price, verdict, etc.), and critical risk like 'forced_directional_risk.' No contradictions with annotations.

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

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

The description is detailed but well-structured: it starts with core purpose, then explains modes, parameters, return values, and usage guidance. Every sentence adds value, though it could be slightly more concise. Still well-organized for a complex 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 fully enumerates return fields (e.g., top_of_book, vwap_fill_price, slippage_pp for single market; theoretical_sum, realizable_sum, capture_ratio for basket). It also covers edge cases like thin_legs and forced_directional_risk. Complete for a complex tool with 4 parameters.

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

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

Schema coverage is 100%, but the description adds value beyond the schema: it clarifies default side behavior for basket mode, interprets size_usd differently for buys vs sells, and explains the required-exactly-one constraint for market/event. This enhances understanding beyond the raw schema.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) with specific details, making the purpose unambiguous and 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?

The description explicitly advises when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about risks of partial basket fills and provides context on when theoretical overround is not capturable.

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, idempotentHint, destructiveHint=false), the description discloses numerous non-obvious behaviors: fees are not modeled so all spread_pp values are gross, compatibility_codes can be non-empty even when matched_pairs>0, unknown legs are never paired, and null temporal_alignment means 'could not be computed' rather than 'aligned'. These details strongly exceed the annotation baseline and contain no contradictions.

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

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

The description is long but information-dense, front-loading the core purpose and using capitalized tokens to delimit modes, safety fields, codes, and counters. Nearly every sentence carries a unique behavioral warning, so it earns its length, though the density prevents it from being as concise as a top score would require.

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 carries the full burden of explaining the return shape, and it delivers: leg-by-leg prices, top_spreads_pp with per-entry flags, safety fields, skipped counters, fee disclosure, and temporal alignment semantics are all specified. Combined with well-documented parameters and strong annotations, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds above-baseline value by framing the parameters as two modes, listing concrete topic examples, and explaining that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. It also clarifies that both modes run the identical token-overlap matcher, giving the agent a richer mental model of parameter interaction.

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 first sentence defines the tool as a cross-venue spread between Kalshi and Polymarket for the same resolving question, and the description then details two clear modes (topic shortcuts vs explicit ticker/slug). It is specific and self-contained, but it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage, so it stops just short of full differentiation.

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

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

The description gives clear internal usage guidance for the two modes and cautions that most pre-mapped topics return compatibility_warning, so pre-mapped is not equivalent to tradeable. However, it never states when to choose this tool over alternatives such as polymarket_arbitrage or polymarket_edges, leaving cross-tool routing implied rather than explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, making the behavioral profile safe. The description adds value by specifying the return format (title, link, published, summary) and the filtering capability, going beyond the annotations.

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

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

The description is two concise sentences front-loading the core purpose and input source, then output and options. Every sentence is essential with no redundancy.

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

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

Despite no output schema, the description fully explains return fields. Parameters are well-covered by schema. The tool is simple and the description provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, with each parameter described adequately (feed source, limit range, query usage). The description adds no further parameter details beyond restating optional filtering, so baseline 3 is appropriate.

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

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

The description clearly states the tool reads a curated travel feed by ID, returns normalized items with specific fields, and optionally filters by keyword. It distinguishes itself from sibling tools like list_feeds by specifying the input source.

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 a prerequisite (feed ID from list_feeds) and mentions optional keyword filtering, giving clear context for when to use. However, it does not explicitly state when not to use or mention alternatives like fetch_feed or search_within.

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

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

Adds context beyond annotations: scoping by identifier, no re-deriving needed. Consistent with readOnlyHint and idempotentHint.

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 action, no wasted words, well-structured.

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

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

Full coverage for a simple tool: explains behavior, scope, return type (value or list), and sibling pairing.

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

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

Description reinforces schema meaning and adds usage: omit key to list all, examples given. Schema coverage 100% so baseline 3, but adds value.

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

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

States specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys' and distinguishes from sibling tools remember and forget.

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

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

Explicitly explains when to use (look up context stored earlier) and provides alternatives (pair with remember/forget) and scoping.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. Description adds behavioral context: returns most recent, carries source/citation_uri/payload, mark_read behavior flags events read so next call shows only newer, and polling works fine. No contradictions.

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

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

Single paragraph, front-loaded with main purpose, then details on return content, filtering, mark_read, and alternative access. Every sentence is informative with no redundancy. Efficient and well-structured.

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

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

No output schema, but description explains return values (source, citation_uri, raw payload). Covers all 5 parameters, behaviors, and alternative access. Complete for a retrieval tool with good annotations. No missing context 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 100%. Description adds beyond schema: clarifies type filters to one subscription type, limit range (1-200, default 50), since as ISO timestamp for fired_at>=, mark_read flags read, unread_only returns only where read_at null. Provides constraints and defaults.

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

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

Clear verb ('Pull') and resource ('fired events from your subscription feed'). Distinguishes from siblings like fetch_feed and read_feed by specifying it returns the most recent alerts with source, citation_uri, and raw payload. Explicit about filtering capabilities.

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

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

Provides practical usage guidance: filter by type and since, set mark_read to affect future calls, defaults (limit 50), and polling-friendly. Also mentions alternative access via GET URL for scripts/dashboards. Gives context for effective use without explicit sibling exclusions but still strong.

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

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

Description goes beyond annotations by detailing fan-out logic, fallback from GDELT to GNews on errors, USPTO soft-fail, accepted input formats, and return structure (changes[], total_changes, citation URIs). No contradiction with readOnlyHint/idempotentHint annotations.

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

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

Description is a single block of text that front-loads example queries and provides comprehensive details. It is informative but slightly verbose; could be tighter while retaining all information.

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

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

Given the complexity of multiple data sources, fallback behavior, and no output schema, the description fully explains what the tool returns (changes grouped by source, total count, citation URIs) and handles edge cases (USPTO deactivation, GDELT/GNews fallback). No gaps.

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

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

Despite 100% schema coverage, description adds value with concrete examples (e.g., '7d', '30d', '1y'), best practice guidance ('Use 30d or 1m for typical monitoring'), and clarifies value accepts ticker or CIK.

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 provides a change feed for a company over a time window, fanned out to SEC, GDELT/GNews, and USPTO. It distinguishes from sibling tool entity_profile by specifying alternative use cases.

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

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

Description provides explicit example queries and guidance on when to use entity_profile instead. However, it does not mention other related tools like fetch_feed or read_feed, missing some sibling differentiation.

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

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

Discloses key behavioral traits beyond annotations: key-value pair storage, scoping by user identifier, and retention policies (persistent for authenticated, 24 hours for anonymous). No contradiction with annotations.

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

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

Description is concise: first sentence states core purpose, second gives usage guidance, third elaborates on storage mechanics. Every sentence adds value, no 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 key-value store with no output schema, description fully covers purpose, usage, storage behavior, and pairing with sibling tools. No gaps.

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

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

Schema descriptions are already clear (key and value with examples). Description adds value by providing concrete example keys, but baseline is high due to 100% schema coverage.

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

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

Description uses specific verb 'Save' and resource 'data', lists concrete examples of what to store, and explicitly 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 states when to use ('when you discover something worth carrying forward'), provides usage examples, and contrasts with alternative actions (retrieve with recall, delete with forget). Also notes persistence differences based on authentication.

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 carrying readOnlyHint/openWorldHint/idempotentHint/destructiveHint, the description still adds substantial behavioral context: multi-match instruments assert nothing and return figi_candidates, unresolved identifiers are explicitly listed under `unresolved` rather than omitted, every identifier is source-labelled, LEI/FIGI enrichment degrades gracefully when GLEIF/OpenFIGI are down, and ISIN-to-LEI mapping works for non-US issuers. This far exceeds the annotation baseline.

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 genuinely long and densely nested with parenthetical chains (e.g., the single sentence covering cross-source identity increasingly buries its clauses), which hurts scanability despite the content being valuable. It is front-loaded with the trigger examples and 'Use FIRST' instruction, but the wall-of-nested-parens structure warrants only a 3.

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 high-complexity tool with no output schema and two heterogeneous entity types, the description is remarkably complete — it covers return fields (figi_candidates, unresolved, CIK/ticker/LEI/RxCUUI), failure/degradation behavior, and input edge cases. It explains what comes back for ambiguous matches and which sources establish identifiers, though it never states a formal success-case return structure, which is the main remaining 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?

Although schema coverage is 100%, the description adds genuinely non-redundant meaning to `value` — the warning to pass the ENTITY NAME ONLY and 'never the question's full noun phrase' because FIGI matches instrument names is critical operational nuance the schema's terse 'brand or generic name' lacks. The type parameter also gains enriched semantics (cross-source identity spine, FIGI non-equity coverage) beyond the enum values.

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

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

The description states a precise verb-resource pair (resolve a spoken NAME to canonical/official identifiers) and opens with concrete trigger examples ('What's the ticker for…', 'find the CIK for…'), making intent unmistakable. It enumerates both supported types (company, drug) and what each resolves to, so an agent can immediately tell this is the name-to-ID gateway 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?

The explicit instruction 'Use FIRST whenever you have a name but need an ID' is strong, unambiguous when-to-use guidance, reinforced by the note that it 'replaces 2-3 manual lookups.' It details accepted input formats (ticker, CIK, ISIN, name) and conditional handling (bonds need issuer name exactly as printed, not the full noun phrase). It lacks explicit when-not-to-use or named sibling exclusions, so it stops 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?

Annotations already declare readOnly and idempotent behavior. The description adds value by explaining the internal process (probes each entity with ai_visibility_check, ranks results) and output details (score, confidence, signal density). This goes beyond the annotations without contradicting them.

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

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

The description is 3-4 sentences with the main purpose front-loaded in the first sentence. Every sentence adds value: purpose, internal mechanism, use case, return type. No fluff or repetition.

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 fairly covers what the tool does and returns (ranked list with score, confidence, signal density). It could be more explicit about the exact output structure, but it is adequate for understanding usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds mild context (first entity as subject, models optional, context for disambiguation) but does not significantly expand on what the schema already provides.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side using ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic) by specifying the process and competitive audit use case.

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

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

The description explicitly says it is useful for competitive AI-marketing audits and implies when to use: when comparing multiple entities. It does not list explicit alternatives or exclusions, but context signals from sibling tools (ai_visibility_check for single entity) provide enough 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, idempotentHint, etc. The description adds substantial behavioral context: fans out to two services, returns multiple data components, and discloses partial failures (bundlephobia may take 5-30s, sources_failed list). 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 somewhat long but packs necessary information: purpose, use case, return details, limitations, alternatives. Every sentence adds value, though some could be tightened. Front-loaded well.

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

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

No output schema, so description fully compensates by listing the exact fields returned (summary block, per-advisory, links, alternatives). Also covers ecosystem scope and partial failure behavior. Extremely 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. The description adds minor context (scoped packages accepted, version defaults to latest) but these are already in the schema. No additional semantics beyond schema.

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

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

The description clearly states it's a composite check for npm packages covering license, advisories, version history, bundle size, etc. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes from siblings by noting that non-NPM ecosystems should use deps.dev directly.

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

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

Explicitly says when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides alternatives: for PyPI/Maven/Cargo/Go, use deps.dev:version directly. This is clear guidance with exclusions.

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

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

The description discloses technical details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also explains output features (character offsets, similarity scores). Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description adds significant behavioral context without contradiction.

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

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

The description is one paragraph of about 100 words, covering purpose, usage, behavior, and output. It is fairly concise and informative, though restructuring into shorter sentences could improve scanability. No fluff; every sentence adds value.

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

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

Despite lacking an output schema, the description explains return values (top-N passages with character offsets and similarity scores), limits (200K chars, 1-20 passages), and technical details (embeddings, windowing). It also positions the tool within a workflow (pair with ask_pipeworx_grounded), making it self-contained for an AI 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% with descriptions for all three parameters. The description reiterates some schema info (e.g., 'max ~200K chars' in text) but adds examples for query and default for limit. Baseline for high coverage is 3; the description adds only marginal semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It provides concrete examples (SEC 10-K body, article, long tool result) and distinguishes itself by emphasizing that it searches within an already-fetched text, saving context. The title 'Search Within a Source' complements this nicely.

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

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

The description explicitly says when to use: 'when the record is too big to cram into the prompt — search_within saves context.' It also suggests a pairing with 'ask_pipeworx_grounded' for grounding over relevant passages. While it does not list when NOT to use, the guidance is direct and practical.

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 behavioral traits beyond annotations: OAuth requirement, SMS rate limits, delivery channel behaviors, and subscription persistence. However, annotations include idempotentHint:true, which contradicts the description's implication that each call creates a new subscription (non-idempotent). This contradiction lowers the score.

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

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

The description is front-loaded with the core purpose, then organized into requirements, types, and delivery channels. It is comprehensive but somewhat lengthy; every sentence adds value.

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

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

Given the tool complexity, the description covers prerequisites, supported types, parameter examples, delivery options, return value, and constraints. No output schema exists, but the description explains the return. It is complete for effective 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% and the description adds extensive context: explains each type with example params, details delivery constraints (phone verification, SMS cap, webhook signing). This significantly enhances understanding beyond the schema.

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

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

The description clearly states the core action: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the resource (subscription) and the result (returns new subscription id). This distinguishes it from sibling tools like list_subscriptions or unsubscribe.

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

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

The description provides explicit context: requires a Pipeworx OAuth account, lists supported subscription types with examples, and explains delivery channels. While it doesn't explicitly state when not to use or alternatives, the sibling context and coverage make it clear. Could improve with direct comparison to related tools.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds that it returns example questions with tool shapes drawn from live catalog, providing additional 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?

Single paragraph but packed with useful information and front-loaded with common queries. No extra words, but could be slightly more structured for readability.

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

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

Given one optional parameter, good annotations, and no output schema, the description covers when, how, and what the tool returns completely.

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

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

Schema has one parameter with description. Description lists valid topic values (finance, pharma, etc.) and explains that omission gives cross-category spread, adding meaning beyond schema.

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

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

The description clearly states it is an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. Distinguishes from siblings like ask_pipeworx and 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and specifies calling with no arguments for full spread or passing topic to focus.

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 value beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. This clarifies the non-destructive nature and lifecycle impact, which annotations only hint at with destructiveHint=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?

Two sentences, front-loaded with the action, no wasted words. Efficiently conveys the core purpose and key behavioral details.

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 single-parameter tool, the description covers ownership, the deactivation behavior, and the tie to recent_alerts. No output schema needed; the description is 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% and the parameter description already states 'Subscription id (uuid) returned by subscribe.' The tool description does not add new semantic meaning beyond what the schema provides, so baseline 3.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from siblings like subscribe and list_subscriptions by mentioning ownership enforcement and deactivation vs deletion.

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

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

The description provides clear context: ownership enforced (only your own subscriptions) and explains the behavioral outcome (deactivated, not deleted). It does not explicitly list when not to use or compare to alternatives, but the context is sufficient for an 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?

Beyond the annotations, the description discloses the verdict set, the semantics of could_not_verify vs unsupported, the presence of verification_error with stage/detail, and the instruction not to treat could_not_verify as evidence. It also notes the efficiency gain of replacing multiple sequential calls. These go well beyond the readOnly/idempotent hints.

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

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

The description is long but front-loaded with trigger phrases and usage intent. Each section adds value: examples, mechanism, return values, and caveats. It could be slightly tightened by reducing redundant phrasing, but the structure is logical and dense with 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?

Given the tool's complexity (two code paths, multiple verdicts, failure modes) and the absence of an output schema, the description fully explains return values, edge cases, and error semantics. It covers both the structured and grounded pipeline, citation, and reasoning, making it self-sufficient 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%, so the baseline is 3. The description adds meaningful context for tolerance_pct by explaining it overrides the implied tolerance and recommending 1-2% for hallucination detection. The claim parameter is given concrete examples, reinforcing the schema descriptions.

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

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

The description clearly states the tool's purpose as 'natural-language claim verification against authoritative sources' and provides explicit trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from sibling tools by detailing the two-path processing (SEC EDGAR fast path vs grounded pipeline) and emphasizing it replaces 4-6 sequential calls.

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

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

The description gives a direct usage directive ('Use whenever the agent needs to check whether something a user said is factually correct') and explains scope by claim type (company-financial vs other). It also explains fallback behavior and tolerance_pct use cases. However, it does not explicitly name alternative tools to avoid, so guidance is strong but not exhaustive.

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