Alienvault Otx

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds crucial context: API key usage (BYO key, direct Anthropic billing), default model, and return structure (per-model details + combined view). No contradictions.

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

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

Four sentences with no redundancy: first sentence states core action and output, second covers model selection and API key, third lists return fields, fourth gives use cases. Front-loaded with the most important information.

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

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

Despite no output schema, the description adequately explains the return structure (per-model score, confidence, signals, raw_response, plus combined view). Parameter descriptions are complete, and use cases are clear. The tool's moderate complexity is well-addressed.

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

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

Schema has 100% coverage with good descriptions. The description enriches parameter understanding: clarifies the default model for 'models', explains that '_apiKey' is passed through to Anthropic (with pricing implication), and adds that 'context' helps disambiguate common names. This exceeds the baseline 3.

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

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

The description clearly states the tool's purpose: probing LLMs for visibility scoring (0-100) of brands/products/topics. It distinguishes from siblings like 'ask_pipeworx' (which queries Pipeworx AI) and 'deep_research' (general research) by focusing on AI visibility audits.

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

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

Explicit use cases are provided ('AI-marketing audits, pre-launch brand checks, competitive monitoring'). The description explains default model (Workers AI) and how to optionally add Anthropic. While it doesn't list exclusions or alternatives, the context is sufficient for deciding when to use.

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

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

Beyond the read-only/idempotent annotations, the description discloses that the tool dynamically routes to a large tool ecosystem, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not discuss failure modes, latency, or the exact shape of the structured answer, but the main invocation behavior is clearly conveyed.

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 an instruction and a categories list, then gives examples and escalation paths; it is well organized and mostly free of filler. It is long because it serves a broad routing tool, but some redundancy around preferring it over web search keeps it from a 5.

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

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

Given no output schema, the description covers the needed ground: what queries to use it for, what it returns (structured answer with citation URIs), when to escalate to siblings, and examples. An agent has enough information to decide to invoke it and to know what answer format to expect.

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

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

The schema already provides 100% parameter coverage, including the required question parameter and five aliases. The description reinforces that the input is a natural-language question and gives examples, but it adds no substantive 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 defines ask_pipeworx as a router that sends factual questions to one of 5,798 tools across 1,517 verified sources and returns structured answers with citation URIs. It is clearly distinct from sibling tools like ask_pipeworx_grounded and deep_research despite the overlapping name.

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 prefer this over web search, enumerates query forms that trigger it ("what is", "look up", "find", "get the latest", "how much", "current"), and gives escalation conditions: use ask_pipeworx_grounded for verbatim evidence/confidence and deep_research for broad/multi-part questions. These instructions are actionable and 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?

The description goes well beyond the annotations by disclosing the beta nature, the possibility of live candidate routing improvements, and the current state where no candidate is active. It also clarifies that the tool is a full working router rather than a fallback or stub. This matches the readOnly and idempotent annotations and adds important context about experimental variability.

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 beta relationship to ask_pipeworx and every subsequent sentence earns its place: current candidate status, usage instruction, comparison purpose, and the clarification that this is a full router. The length is appropriate for the nuance of a beta router without being bloated.

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 identity, current behavior, usage context, and relationship to the stable router, which is sufficient for invocation. It relies on ask_pipeworx for the exact response shape and parameter details rather than spelling them out, which is reasonable given the sibling context. A slightly more explicit statement of expected return behavior would make it fully standalone.

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

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

Schema description coverage is 100%, with all aliases such as q, text, input, query, and prompt documented in the input schema. The description adds only that the tool takes the same arguments as ask_pipeworx, which is useful but not necessary given the schema already fully explains the parameters. This meets the baseline for schema-heavy tools without adding significant new semantic detail.

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 beta version of ask_pipeworx acting as a universal router over 5,798 tools with the same arguments and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge while still being a full working router. This leaves no ambiguity about what the tool does or how it relates to its primary sibling.

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 it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. It also clarifies that it is not a fallback and currently behaves identically to ask_pipeworx. It does not fully enumerate exclusions or differentiate from ask_pipeworx_grounded, so it stops just short of perfect guidance.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. It adds substantial behavioral detail beyond those hints: the refusal mechanism with specific refusal_reason values, the exact success return shape including verbatim evidence and confidence, and the fact that answers are extracted using ONLY the tool result.

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 front-loads the core value proposition, then explains routing, return shape, refusal behavior, use cases, and cost trade-off. The inclusion of specific refusal_reason values and the comparison to ask_pipeworx is essential for correct agent behavior, not 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?

This is a complex tool with no output schema, but the description compensates fully by specifying both the success payload and the refusal payload, including all refusal reason options. It also covers the operational effect (extra LLM call), the relationship to ask_pipeworx, and appropriate use cases, so an agent has enough context to invoke it correctly and interpret its result.

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

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

The input schema has 100% description coverage for the single required parameter 'question' and documents its aliases, so the schema already carries the semantic burden. The description does not add parameter-level detail, but none is needed; 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 uses a specific verb phrase — 'hallucination-resistant answer mode' — and precisely identifies the resource and behavior: it routes through the same tool-finding machinery as ask_pipeworx, fetches data, then extracts an answer only from the tool result. It clearly distinguishes itself from ask_pipeworx by emphasizing grounded, evidence-backed answers for high-stakes reads.

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?

Usage conditions are explicit: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' followed by concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also gives an exclusion rule — 'prefer ask_pipeworx for casual lookups' — and explains the extra cost of one LLM call, making the selection decision 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?

The description extensively discloses behaviors beyond annotations, including resolver contract, parent event extraction, news field fallbacks, safety short-circuits for low-confidence matches and closed markets, spread liquidity checks, and cancellation rule parsing. 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, front-loading purpose and usage before detailing behavior. While not concise, the complexity justifies the length, and it remains logically organized.

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, the description is fully complete, covering all behavioral aspects, safety mechanisms, response shapes, and edge cases (e.g., closed markets, wide spreads, cancellation rules). 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?

With 100% schema coverage, the description adds significant value by explaining the market parameter flexibility (slug, URL, or question text), depth options (quick vs thorough default), and include_raw behavior (recommended false). Examples clarify usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison), distinguishing it from sibling tools by its comprehensive research focus.

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

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

The description explicitly recommends use for queries like 'should I bet on X' and provides classifiers and fan-out examples. While it lacks explicit when-not-to-use guidance, the extensive details effectively imply appropriate contexts.

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

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

Adds substantial context beyond annotations: explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, sorts by primary metric, and returns paired data with citation URIs. No contradictions with readOnlyHint, openWorldHint, etc.

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

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

The description is a single dense paragraph but front-loaded with trigger phrases. It covers all necessary information without excessive verbosity, though a slightly more structured format could improve readability.

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

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

Despite lacking an output schema, the description adequately explains return format (paired data + citation URIs) and data types. It covers parameter details and usage context, making it complete for a comparison tool.

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

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

Both parameters are fully described in schema (100% coverage), but the description adds meaningful examples for each enum value of 'type' and specifies use of tickers/CIKs for companies and drug names, along with cardinality constraints.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with trigger phrases like 'Compare X and Y' and 'X vs Y'. It distinguishes from sibling tools like entity_profile by emphasizing parallel 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?

Explicitly recommends preferring this tool over sequential single-pack lookups when comparing entities, providing clear when-to-use guidance and stating it replaces 8-15 sequential lookups.

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

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

The annotations already signal read-only, idempotent, open-world behavior, and the description adds substantial beyond them: account/pricing requirements, parallel routing across 5,798 tools, findings packet structure, gaps[] and contradictions[], citation_uri fetchability, semantic excerpting, and latency expectations. There is no contradiction with 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 long but front-loaded with the most decision-critical facts: account requirement, when to prefer ask_pipeworx, and the core research scope. Each section adds distinct operational knowledge, though a few phrases are dense and somewhat repetitive.

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 covers the return contract: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers auth, pricing, latency, and alternatives, so an agent has enough context to decide whether and how to call the tool.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds useful extra meaning about depth behavior (standard/thorough contradiction scans, thorough requiring a paid plan, multi-step resolution) and question suitability examples, going beyond the schema descriptions.

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

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

The description states a specific verb ('research') and a specific resource ('Pipeworx's 1517 structured data sources'), and explicitly says 'this is NOT open-web search.' It also names the sibling tool ask_pipeworx as the alternative, so an agent can distinguish deep_research without opening the schema.

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 explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead.' It also names the exact alternative tool and the condition for choosing it: 'If you are not signed in, use ask_pipeworx instead.'

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it returns top-N results with schemas and that results are ready to call directly, no second schema lookup needed. This is valuable beyond annotations, though it doesn't detail rate limits or potential side effects (none expected).

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; front-loaded with purpose. While the second sentence is somewhat lengthy, it packs essential information without fluff. Could be slightly more condensed but still efficient.

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

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

Given no output schema, description explains return format (names, descriptions, schemas, examples) and usage pattern. All parameters documented. Adequate for a discovery tool, though missing explicit mention of pagination or result count limits beyond schema.

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

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

Schema coverage is 100%, so schema already documents all 6 parameters with descriptions. Description repeats alias info already in schema. No additional semantic depth beyond what 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 it is a tool discovery/search function with specific verb 'Find tools' and enumerates many domains. Clearly distinguishes from siblings which are specific data tools; this is a meta-tool for navigation.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available'. Provides clear context and exclusionary 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 mark it read-only, open-world, idempotent, non-destructive, and the description adds substantial behavior beyond that: it fans out across multiple sources, soft-fails when the USPTO patents API is sunset, distinguishes empty sections as real no-data (not bugs), and explains name resolution and private-company behavior. No contradiction with annotations.

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

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

The description is long and dense, but front-loaded with intent examples and the key 'one parallel call' positioning. Nearly every section adds necessary operational detail for a complex tool; it could be shortened slightly, but it is structured and earns most of its length.

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

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

With no output schema, the description carries the full burden of explaining what is returned and what failure looks like. It enumerates all response sections (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI), plus sources_used/sources_failed and the private-company resolved:false case. Nothing essential 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?

Input schema already documents both parameters at 100% coverage, so baseline is 3. Description adds valuable semantics: type values are interchangeable, value can be a ticker, zero-padded CIK, or company name, and names resolve via SEC EDGAR. This goes beyond the schema's wording.

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 a specific purpose — full cross-source profile of a US public company in one parallel call — and differentiates itself from chaining single-pack lookups. Example natural-language triggers clarify when it matches user intent. This clearly separates entity_profile from siblings like resolve_entity or compare_entities.

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

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

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', giving a direct when-to-use rule and naming the alternative approach. It also covers edge use cases: private companies resolve to resolved:false with notes rather than a bare failure.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true, so the description adds value by noting sensitive data clearing, but does not repeat safety profile.

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, no unnecessary words. Every sentence earns its place.

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

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

For a simple delete operation, the description fully explains purpose, usage context, and sibling relations. No output schema needed.

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

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

Schema coverage is 100% with a clear description for 'key'. The tool description adds minimal extra meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying a unique verb and resource, and distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task done, or clearing sensitive data. Mentions pairing with siblings, but no explicit when-not-to-use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds process details (fetching, extraction, emission of markdown) that enrich understanding without contradicting annotations. It doesn't disclose additional behavioral traits like rate limits or authentication, but the existing annotations cover the key safety aspects.

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

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

Three sentences with no fluff: first sentence states purpose and process, second details output, third lists use cases. Every sentence adds value. Front-loaded with the most important information.

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

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

Given the absence of output schema, the description clearly describes the output format ('standard llms.txt markdown format', 'single text blob') and its intended placement. With only two parameters both fully described in schema, no additional context is needed.

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

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

Schema coverage is 100% for both parameters. The description only mildly reinforces by mentioning 'Full URL' and default/max for max_links, but adds no new semantics beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description starts with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It then details the process (fetch, extract, emit) and output format, clearly distinguishing this from sibling tools which cover unrelated domains like betting, arbitrage, or search.

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 use cases: getting a client site indexed, drafting for own project, and auditing a competitor. While it doesn't state when not to use or name alternatives, the provided use cases are sufficient and no sibling tool competes directly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true; description adds detail on accessed data (full description, references, etc.) without contradicting.

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

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

Single sentence, front-loaded with purpose, 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 annotations covering safety, output schema present, and description listing output fields, tool is fully specified.

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

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

Schema has 100% coverage with clear description of pulse_id as hex string; description lists output fields but adds no new parameter meaning.

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

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

The description uses specific verb 'fetch' and resource 'single OTX pulse', listing key attributes. It clearly distinguishes from sibling 'search_pulses' which is for multiple.

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?

Implicitly indicates use when needing a specific pulse by ID (single), but lacks explicit comparison to search_pulses or when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no new behavioral traits beyond confirming it's a list operation; it is consistent but provides no additional context like auth needs or rate 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?

The description is two sentences, front-loaded with the action and resource, includes return fields and usage hint. 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?

Given the tool's simplicity (1 optional parameter, no output schema), the description fully covers purpose, input, output fields, and usage context. No gaps.

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

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

Schema coverage is 100% and already describes the sole parameter 'include_inactive'. The description does not add parameter semantics beyond what the schema provides, 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 lists active subscriptions and specifies the fields returned, but does not explicitly differentiate from sibling tools like 'subscribe' 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 gives clear when-to-use guidance (reviewing subscriptions before adding more or finding an ID to cancel), but does not mention alternatives or when not to use.

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

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

Annotations already establish readOnly, openWorld, idempotent, and non-destructive behavior, so the description does not need to restate those. It adds valuable context beyond annotations: type auto-detection, the return payload (threat-intel pulses plus observed-context fields), and the forgiving nature of the type parameter. No contradictions are present.

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

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

The description is three purposeful sentences: the first lists supported indicators, the second explains return value and use cases, and the third clarifies auto-detection. Every sentence adds distinct information with no repetition or filler, and the structure front-loads the core action.

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

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

Given the tool's simplicity (2 parameters, high schema coverage, output schema present, comprehensive annotations), the description is sufficient. It explains what the tool does, what it returns, and how the optional type parameter behaves. The presence of an output schema means detailed return fields need not be listed in the description.

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 extra meaning by explaining that 'type is auto-detected when omitted' and that the type parameter is only needed to override detection. It also gives concrete examples for each type, complementing the schema's enum and 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 specific verb ('Look up') and resource ('threat indicator in OTX'), enumerating exact input types (IPv4/IPv6, domain, URL, hash, CVE). It clearly distinguishes the tool from siblings like get_pulse or search_pulses by focusing on indicator-to-pulse mapping rather than arbitrary search or pulse retrieval.

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 via example questions ('which campaigns exploit a given CVE', 'whether an IP is known-malicious') that indicate suitable use cases. It does not explicitly name alternative tools or say when not to use this tool, but the examples make the intended usage obvious, placing it just below an explicit exclusion list.

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

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

Annotations are all false, so the description carries the full behavioral burden. It discloses key behaviors: filing returns a claim_token, passing that token later reads the resolution status, rate limiting ('5 per identifier per day'), and that it is free and doesn't count against quota. It also warns not to paste end-user prompts and specifies how to frame feedback. This goes far beyond the annotations and provides rich behavioral context.

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

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

The description is longer than average but well-structured and front-loaded with the core purpose, then usage, exclusions, mechanics, and constraints. Every sentence adds meaningful information (scope, token flow, rate limits, quota). It is dense but not wasteful, earning a solid 4.

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

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

With no output schema, the description explains the return mechanism: 'Filing without an account returns a claim_token; pass it back later... to read whether it was fixed and what changed.' It also covers rate limiting and scope. While it doesn't detail the exact response structure, it provides enough for the agent to use the tool effectively. Slightly more detail on the response object would push it to 5.

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 value by explaining the claim_token usage pattern ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), which is not in the schema description. It also clarifies the type parameter's enum meanings through examples. This extra context lifts it above the baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the scope (feedback about Pipeworx tools), distinguishing it from sibling tools like ask_pipeworx or discover_tools by focusing on reporting bugs, feature gaps, and praise.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file with other MCP servers for unrelated tools. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds valuable context: data source (CF analytics-engine), no PII, caching policy (5min-1h). No contradictions.

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

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

Two compact sentences with a bulleted list of use cases. Front-loaded with key output. No redundant information; 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 tool with one parameter and no output schema, the description covers all necessary context: output items, window options, use cases, data source, privacy, and caching. No gaps.

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

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

Schema coverage is 100% with enum values. Description adds semantic value by explaining the trade-off of window sizes: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agent choose appropriately.

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 returns trending information (top tools, packs, call volume) over recent windows. Differentiates from sibling tools like discover_tools or ask_pipeworx by focusing on aggregated usage data from other AI agents.

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

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

Explicitly lists three specific use cases (discovering hot data sources, confirming popular tool, aligning with agent needs). Does not explicitly state when not to use, but the use cases provide strong guidance. Could mention it's not for historical trends or individual user data.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: fill check against live CLOB depth, semantic anchor for cross-event pairs, partition filter for placeholder slugs, and response details. 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 lengthy but well-structured with sections and examples. It packs a lot of information without unnecessary verbosity. Could be slightly more concise, but given the complexity, it earns its space.

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

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

Given no output schema, the description fully explains the response structure (opportunities array, partition_check object) and key behaviors (fill check, semantic anchor, partition filter). It covers all essential aspects for the agent to use the tool correctly.

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

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

Schema description coverage is 100% (both event and topic have descriptions). The description adds extra meaning: event accepts slugs or full URLs, topic accepts seed questions, and clarifies default behavior with no args. Slightly above baseline 3 due to the added context.

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk, and provides specific methods (trending_scan, event, topic).

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 each mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It recommends event for a specific market and explains cross-event mode catches patterns missed by single-event. Provides usage examples for event and topic parameters.

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

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

The description extensively discloses behavioral traits beyond annotations: it details the three response segments, output fields (edge_pp_net, kelly_fraction, etc.), tradeable-edge knobs (min_liquidity, max_spread_pp), diagnostics section, and caching policy ('Cached 1h at the KV level'). 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 long but well-structured with clear sections (model families, output fields, knobs, response structure). It front-loads the purpose. However, some technical details (e.g., 'lognormal barrier from 90d FRED log-returns') are verbose but necessary for domain understanding.

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 (9 parameters, no output schema), the description is remarkably complete: it explains the output structure (by_segment, fed_candidates, _diagnostics), edge and Kelly fields, filters, and caching. No missing pieces for an agent to use the tool correctly.

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

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

Although schema coverage is 100%, the description adds meaningful context for parameters like min_liquidity ('drop thin-book opportunities'), max_spread_pp ('tight books'), and min_partition_leg_kelly ('suppress thin partitions'). It explains how knobs filter opportunities and provides examples, going beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies that it's built for 'what should I bet on today' and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on disagreement with Pipeworx data and providing comprehensive edge analysis.

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

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

The description gives explicit usage context: built for discovering opportunities without paging hundreds of markets. It explains the three segments and the Fed bets exclusion. However, it does not explicitly tell when to use this tool versus its siblings, though the sibling names imply alternatives.

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

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

The description adds significant behavioral details beyond annotations: it explains the response structure (tracked, expired, snapshot_dates), field meanings (first_seen, trend, decay_pp_per_day, lifespan_days), and limitations (60-day TTL, snapshot start, daily closes vs intraday). No contradictions with annotations.

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

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

The description is informative but somewhat long. It is front-loaded with purpose, then details output fields and limitations. Every sentence adds value, but could be slightly more concise.

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

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

Given no output schema, the description thoroughly explains the return format and fields. Parameters are well-described, limitations are stated, and the tool's context relative to snapshots is clear. Complete 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 parameters are already documented. The description adds usage context: days default and clamp range, window meaning and default. This provides practical 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: edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge age and trend, and distinguishes itself from the sibling tool 'polymarket_edges' by focusing on historical analysis rather than current snapshots.

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

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

The description provides context on when to use the tool (to understand edge history and decay) and contrasts fresh vs old edges. However, it does not explicitly state when not to use or mention alternative tools for different purposes.

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

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

Annotations (readOnlyHint=true, destructiveHint=false) already indicate safety. The description adds significant behavioral context: walks the ladder, returns verdicts, warns about forced directional risk in baskets. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections and bolded key points. It front-loads the core purpose and every sentence adds value. Could be slightly tighter, but appropriate given complexity.

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

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

No output schema exists, so the description must cover return values. It thoroughly lists output fields for both modes, including verdicts, per-leg details, and risk indicators. With annotations covering safety, the description is fully complete.

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

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

Schema description coverage is 100%, but the description adds meaning beyond schema: explains the market vs event mode requirement, defaults, and how size_usd interpretation differs between modes. It also describes auto side detection for baskets, enriching parameter understanding.

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

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

The description clearly states the tool checks realizable vs theoretical edge against live CLOB order-book depth. It explicitly distinguishes two modes (single-market and basket) and references sibling tools like polymarket_arbitrage and polymarket_edges, indicating when this tool should be used instead.

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

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

The description explicitly states 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 explains the consequences of partial fills, providing clear context for use.

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

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

Goes far beyond read-only/idempotent annotations: explains why spreads can be 2–25pp apart, that the fee schedule is not modeled (gross spread), that compatibility_codes can be non-empty even with matched_pairs > 0, and the exact semantics of temporal_alignment nulls. This is unusually complete behavioral disclosure.

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 the tool is genuinely complex and the length is earned. It is front-loaded with the core purpose and modes, and uses capitalization ('TWO MODES', 'RESPONSE', 'SAFETY FIELDS') to create structure. It could still be tightened with bullets, but every substantial fact earns its place.

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

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

With no output schema, the description carries the full burden of explaining the response, and it delivers: raw prices, top_spreads_pp, compatibility codes with meanings, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment semantics, fees_note, and skipped counters. Nothing essential is missing for an agent to invoke and interpret the tool.

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

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

Even though schema coverage is 100%, the description enriches the parameters substantially: the topic list is a named macro shortcut set, explicit ticker/slug override their mapped side, and both modes run the identical token-overlap matcher with the same disclosures. This maps parameter combinations to tool behavior.

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?

Opens with the exact resource ('Cross-venue spread between Kalshi and Polymarket for the same resolving question') and a specific verb of comparison. The two modes are explicitly scoped, and the tool is clearly distinguishable from single-venue sibling tools like polymarket_edges.

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

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

The description gives strong situational guidance: when bet shapes are equivalent the spread is a real signal, when not the tool says so; pre-mapped shortcuts frequently yield compatibility warnings and 'pre-mapped ≠ tradeable.' It does not explicitly name sibling alternatives or state when not to use this tool, so it misses the top bar.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping to an identifier and pairing with remember/forget, but doesn't need to repeat the safety profile.

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

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

The description is a single, dense paragraph with no wasted words. It front-loads the main purpose and provides essential context efficiently.

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 fully explains behavior, scoping, and related tools. It is complete and leaves no ambiguity.

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

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

Schema coverage is 100% with a clear description for the only parameter. The description restates that omitting the key lists all keys, adding little beyond the schema. Baseline 3 applies.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys when the key is omitted. It specifies the verb (retrieve/list) and the resource (saved values/keys), and distinguishes from siblings like remember and forget.

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

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

The description explains when to use: 'to look up context the agent stored earlier' and provides concrete examples (ticker, address, notes). It mentions scoping and pairing with remember/forget, though it doesn't explicitly state when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the return format (source, citation_uri, payload), the mark_read behavior for tracking read state, and the polling suitability, which are beyond the annotations.

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

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

The description is concise (5 sentences), front-loaded with the purpose, and every sentence provides essential information without redundancy.

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

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

For a tool with no output schema and 5 optional params, the description covers return values, parameter effects, and even mentions an alternative access method. It 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%, but the description adds extra meaning: explains filter by type and since, and how mark_read affects subsequent calls ('so the next call only shows newer ones'). This enhances understanding beyond parameter 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 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes itself from siblings by focusing on recent alerts from the feed, while siblings like list_subscriptions or recall have different scopes.

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

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

The description mentions that polls work fine and provides an alternative REST endpoint for scripts/dashboards, offering context. However, it does not explicitly exclude other tools or provide detailed when-to-use vs. alternatives, so it loses a point.

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 behavioral details: fan-out to multiple sources, fallback behavior, soft-fail for USPTO, and output structure (changes[] grouped by source, total_changes, citation URIs). No contradiction.

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

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

The description is a single paragraph but front-loaded with examples, then logically covers sources, parameters, and output. Some whitespace or structure could improve readability, but it's concise and informative.

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

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

The tool has 3 parameters, no output schema. The description explains the output format and behavior thoroughly, including fallback and limitations. For a read-only tool, this is highly complete.

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

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

Schema description coverage is 100%. The description enriches parameter meaning: for since, explains ISO date vs relative shorthand and recommends '30d'/'1m'; for value, specifies ticker or CIK; for type, clarifies only 'company' is supported.

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

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

The description clearly states the tool returns a combined change feed (SEC filings, news, patents) for a company in a time window. It distinguishes from sibling tool entity_profile and provides example queries for context.

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

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

The description explicitly gives usage patterns ('What's new with X', 'latest on Y') and contrasts with entity_profile for static profiles. It explains fallback logic (GDELT→GNews) and advises on typical since values ('30d' or '1m').

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 idempotentHint=true and destructiveHint=false. The description adds that storage is key-value and scoped by identifier, with 24-hour retention for anonymous sessions. This provides useful 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?

Extremely concise: four sentences covering purpose, usage, behavior, and pairing. No wasted words. Front-loaded with the core action.

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

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

For a simple two-parameter tool with no output schema and clear annotations, the description is fully complete. It explains persistence, scoping, and how to pair with other tools.

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

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

Schema covers 100% of parameters with descriptions. The description adds contextual examples for key ('subject_property') and value ('findings, addresses'), enhancing understanding of how to use 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 states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the action (save), resource (data), and distinguishes from sibling tools like 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?

Explicit guidance on when to use: 'Use when you discover something worth carrying forward.' Mentions pairing with recall and forget, and describes session persistence differences for authenticated vs anonymous users.

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

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

The description goes well beyond the readOnly/idempotent annotations, explaining internal cascading lookups, graceful degradation when LEI/FIGI enrichment is unavailable, explicit `unresolved` fields, ambiguous-match behavior, and return formatting like `figi_candidates`. There is no contradiction with annotations; all described behavior aligns with a read-only, idempotent resolver.

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

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

The description is dense and verbose, but it is front-loaded with immediate usage examples and the key 'use first' instruction. Complexity is high enough to justify many caveats, though some sentences are extremely long and could be split for clarity. Overall it earns its length but sacrifices conciseness.

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

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

With no output schema, the description carries full responsibility for explaining return behavior, and it does so thoroughly: source-labelled identifiers, unresolved fields, candidate lists for ambiguous matches, RxNorm citations, and parent/child ownership data. It also covers graceful failure modes and entity-type specifics, making it complete enough for an agent to invoke correctly.

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

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

Even though the input schema covers both parameters at 100%, the description adds substantial meaning: accepted input formats for `value` (ticker, CIK, ISIN, name), type-specific behavior, and a critical usage warning about passing only the entity name rather than a full noun phrase. This meaningfully exceeds 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 identifies the tool as resolving user-spoken names into canonical/official identifiers, with concrete examples like ticker, CIK, LEI, and RxCUI. It differentiates itself from sibling tools by focusing on supplying IDs that other tools require as input, and it specifies supported entity types upfront.

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 an explicit directive: use this tool first whenever you have a name but need an ID. It also explains coverage boundaries, such as non-equity instruments and ambiguous matches returning candidates. It does not name alternative sibling tools or state explicit non-use conditions, but the primary routing guidance is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: it ranks by score, surfaces most/least recognized, and uses the context parameter to disambiguate common names. 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?

Three sentences: first states purpose, second explains process, third provides usage scenario and output format. Front-loaded and efficient.

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

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

No output schema, but the description covers the return structure (ranked list with score, confidence, signal density). Handles all 4 parameters with clear explanations, and differentiates from sibling tools like ai_visibility_check.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying that the first entity is treated as the 'subject' for narrative, which is not in the schema.

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

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

The description starts with a specific verb and resource ('Compare AI visibility across multiple entities side-by-side'), clearly distinguishing it from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (generic comparison).

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

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

The description explicitly states it's useful for competitive AI-marketing audits and gives an example question. It mentions it probes each entity using 'ai_visibility_check', implying that for a single entity one should use that tool directly, but does not explicitly state when not to use this tool.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are present, but the description adds substantial context: the composite fan-out architecture, partial failure handling (sources_failed list), and timing behavior (5-30s delay on first bundlephobia measurement). No contradictions.

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

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

The description is front-loaded with the main purpose and uses multiple sentences, each earning its place (use cases, ecosystem scope, failure behavior, timing). It is slightly long but appropriately detailed for a complex tool; no filler or 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 having no output schema, the description lists the exact fields returned (summary block fields, per-advisory, links, alternative versions). It covers parameter usage, failure modes, and ecosystem limitations, making it a complete and self-contained description for the 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 both parameters. The description adds value by explaining the composite check and output fields, but does not provide additional syntactic constraints beyond the schema. It is slightly above baseline by offering concrete examples and context for parameter usage.

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

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

The description clearly states the tool's composite nature (deps.dev + bundlephobia), specific resources (npm packages), and explicit use cases ('is X safe / popular / small' and 'what does adding lodash cost me'). It distinguishes itself from siblings by focusing on npm ecosystem and composite checks, while no sibling tool shares this exact purpose.

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

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

The description explicitly tells when to use ('whenever an agent asks...') and when not to ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). It also provides timing caveats for bundlephobia and notes graceful degradation, giving clear guidance on expectations.

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, fully covering the safety profile, so the bar is lower. The description adds the return field list and the matching behavior (title/description only), which adds some value beyond annotations but doesn't describe pagination or result limits beyond the schema.

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

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

Three sentences, zero wasted words. The description front-loads the core purpose, lists return fields compactly, and wraps up with a critical exclusion note. Every sentence earns its place with substantive 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?

The tool has an output schema, so return values are documented elsewhere. The description covers purpose, exclusions, return fields, and behavioral nuance (title/description matching) — quite complete for a read-only search tool with good annotations and full schema coverage. Minor gap: no mention of result ordering or date scoping, but this is well-covered overall.

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

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

Schema description coverage is 100%, so the schema fully documents all 3 parameters (query, page, limit). The description adds the crucial semantic context that query matches titles/descriptions rather than indicator values, which is meaningful. However, it doesn't add format or type details beyond the schema, landing at the baseline 3.

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

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

The description uses a specific verb+resource ('Search OTX threat-intel pulses') with concrete search terms ('campaign, malware family or actor name') and even provides examples ('ransomware', 'APT29'). It clearly distinguishes itself from siblings like lookup_indicator and get_pulse by specifying the keyword-based search scope.

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

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

The description explicitly states when to use this tool (keyword search on pulse titles/descriptions) and explicitly when NOT to use it — for bare indicator values (IP, domain, hash, CVE), directing the agent to lookup_indicator as the alternative. This is fully explicit with both when and when-not 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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds crucial behavioral details: truncation at 200K chars, BGE-base-en embeddings, cosine similarity over 500-char windows, and output offsets for verification. No contradiction with annotations.

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

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

The description is a single paragraph with the main purpose front-loaded. It is efficient but includes some technical depth (embedding model, window sizes). Almost every sentence earns its place, though a slight reduction in technical detail could improve conciseness.

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

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

Given the tool's complexity (semantic search, truncation, offsets, pairing with another tool), the description covers all essential aspects: what it does, when to use, technical constraints, and output features. No output schema exists, but the description mentions return content (passages with offsets and scores).

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 minimal extra meaning: for text it repeats the max length, for query it adds examples. It does not significantly enhance understanding beyond the schema descriptions.

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

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

The description starts with a clear verb+resource: 'Semantic search INSIDE a fetched record.' It specifies the action (search) and the target (a fetched record), and the context of use distinguishes it from siblings like 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?

The description explicitly states when to use this tool ('when the record is too big to cram into the prompt') and pairs it with a sibling tool (ask_pipeworx_grounded). It provides clear context but does not explicitly state when not to use it or list direct alternatives.

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

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

The description fully discloses behavioral traits: it creates a subscription, returns an ID, and requires OAuth. It details delivery constraints (phone verification, 10 SMS/day cap, webhook signing secret delivered once, auto-disable after 10 failures). Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) are consistent and complemented by the description, which adds context about persistence and side effects.

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: a concise opening sentence, followed by enumerated supported types with examples, then delivery channel details. Every sentence adds value; there is no redundancy. Despite its length, the structure makes it easy to scan, and it is front-loaded with the core 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?

Given the tool's complexity (3 parameters, nested objects, multiple enums, no output schema), the description is complete. It explains the return value ('Returns the new subscription id'), all input options, and constraints. It covers edge cases (phone verification, SMS cap, webhook secret delivery). No gaps are evident.

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 significant meaning beyond the schema: it provides concrete examples for each `type`'s `params` object (e.g., `sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}`), explains required fields for `clinical_trial`, and expands on `delivery` constraints (verification, caps, webhook signing). This extra detail greatly enhances parameter understanding.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the action (subscribe), the resource (alerts/event stream), and distinguishes from siblings like `list_subscriptions`, `unsubscribe`, and `recent_alerts`. Supported subscription types are enumerated with examples, making the tool's role unambiguous.

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

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

The description explains when to use the tool (to create a monitoring subscription) and includes important prerequisites: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It provides context for each subscription type and delivery channel, but does not explicitly contrast with alternative tools (e.g., `list_subscriptions` for reading). However, the sibling list implies the distinction, and the usage guidance is sufficiently clear 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?

Annotations already mark it as readOnly, openWorld, idempotent, and not destructive. The description adds valuable behavioral details: it returns category-bucketed questions with exact tool arguments drawn from a live catalog, and that it can be called without arguments or with a topic filter. No contradictions with annotations.

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

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

The description is front-loaded with user query examples and clearly presents purpose and usage. It is slightly verbose with multiple example queries, but each sentence earns its place by providing context or guidance. Could be more concise, but remains clear.

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 simplicity of the tool (one optional parameter, no output schema), the description provides a complete picture: it details the return format (category-bucketed questions with tool shapes), usage options, and when to use it. Annotations cover safety and idempotence. 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 covers the single optional parameter 'topic' with 100% description coverage. The description enhances this by listing concrete examples (e.g., 'finance', 'pharma', 'betting') and explaining that omitting it gives a cross-category spread. This adds significant meaning beyond the schema's generic description.

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

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

The description clearly states it returns category-bucketed example questions with tool+argument shapes, and explicitly positions it as the onboarding entry point when the agent doesn't know what Pipeworx can do. It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on generating ideas.

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

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

The description provides clear use cases: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to call with no arguments for a full spread or pass a topic to focus. While it doesn't explicitly contrast with alternatives, the context is sufficient for an agent to decide when to invoke this tool.

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

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

Description adds significant behavioral context beyond annotations: it explains that the subscription is deactivated (not deleted) and that historical events remain available via 'recent_alerts'. This enhances understanding of the tool's side effects and complements the annotations (destructiveHint=false, idempotentHint=true). No contradictions.

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

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

Two sentences, no wasted words. First sentence states the action and key constraint (ownership); second explains the deactivation behavior and consequence. Front-loaded and efficient.

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

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

Given the tool's simplicity (one parameter, no output schema, good annotations), the description covers purpose, ownership constraints, side effects (deactivation), and references another tool for historical events. It fully equips an agent to decide when and how to use this tool.

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

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

The only parameter 'id' is fully described in the schema as 'Subscription id (uuid) returned by subscribe.' The description just says 'by id', adding no additional meaning. With 100% schema coverage, the description does not need to add more, but it also does not enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id.' Verb 'Cancel' and resource 'subscription' are specific. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation and adding ownership enforcement and deactivation behavior.

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 explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding when the tool is applicable. It also notes that the row is deactivated, not deleted, which implies safe usage. While it does not explicitly list alternatives, the context is clear given sibling tools.

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

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

Beyond annotations (read-only, idempotent), the description discloses significant behavioral details: routing logic (SEC EDGAR vs grounded pipeline), verdict types, the crucial caveat that 'could_not_verify' means the check did not happen and must not be shown as evidence, and error reporting with verification_error. This is rich, actionable context.

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

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

The description is dense but well-structured, starting with examples and then covering routing, return values, and caveats. While longer than minimal, every sentence earns its place given the tool's complexity; slightly less concise than ideal but highly informative.

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

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

Despite no output schema, the description explains return verdicts, grounded/structured values, citations, and error semantics. It covers edge cases (could_not_verify vs unsupported) and efficiency benefits, making it complete for invocation decisions.

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

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

Schema covers 100% of parameters with descriptions. The description adds extra operational meaning, e.g., setting tolerance_pct to 1–2 for hallucination detection and noting default behavior. This goes beyond the schema's baseline.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It uses specific verbs like 'fact check', 'verify', and 'confirm or refute', and distinguishes itself by describing the fast path for company-financial claims and fallback for other claims, differentiating it from sibling tools like ask_pipeworx_grounded and lookup_indicator.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains routing for different claim types. It does not name alternative tools explicitly or state when not to use, but it implies it replaces sequential calls, giving strong contextual guidance.

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