Data Austin

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 that it probes per model, returns per-model {score, confidence, signals, raw_response} plus combined view, and that Anthropic requires a BYO key. It does not contradict annotations and provides useful behavioral context beyond them.

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

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

Four sentences, front-loaded with main purpose, then details on models/API key, return format, and use cases. No redundant 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?

Despite no output schema, the description explains return structure (per-model + combined). Covers required and optional parameters. Missing details on how scoring works or what 'signals' are, but overall complete for a probing tool with good annotations.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds minimal extra meaning (e.g., default model is free, API key goes to Anthropic), but mostly repeats schema content. Baseline of 3 is appropriate as parameters are well-documented in schema.

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

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

The description clearly states it probes LLMs for knowledge about a business and scores visibility per model (0-100). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on multi-model visibility scoring and default free model. Use cases (AI-marketing audits, brand checks) are explicit.

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

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

The description gives contexts like AI-marketing audits and brand checks, and explains when to use the optional API key for Anthropic. However, it does not explicitly state when NOT to use or compare to direct siblings, so it lacks complete exclusion guidance.

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

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

The annotations already mark it read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context: it fills arguments automatically, works on all tiers, is a single fast call, returns stable citation URIs, and routes live-news queries to news packs. No hidden mutation is implied, and nothing contradicts 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 dense and front-loaded with the most important routing guidance, then examples, then escalation paths. It is longer than the minimum, but almost every sentence carries decision-relevant information; only minor redundancy such as 'even if web search could also answer it' after 'prefer 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?

For a one-required-parameter routing tool, the definition is complete: it specifies what questions to send, what will happen (source selection, argument filling, structured answer with citations), and which sibling tools to use as upgrades. No output schema exists, but the description covers the essential return characteristic without needing to enumerate every schema.

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

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

Schema description coverage is 100%: all six parameters are aliases of 'question', and the schema already describes it as a natural-language question. The description's examples reinforce the accepted input style but don't add parameter-level meaning beyond the schema, so the high-coverage baseline of 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 identifies a specific action—routing a natural-language question to one of 5,798 tools across 1,517 sources and returning a structured answer with pipeworx:// citations. It clearly distinguishes this default tool from ask_pipeworx_grounded and deep_research, and the subject scope (SEC, FDA, FRED/BLS, weather, news, etc.) is explicit.

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

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

It gives explicit when-to-use triggers ('what is', 'look up', 'find', 'get the latest', factual questions) and when-not-to-use alternatives: use ask_pipeworx_grounded for verbatim grounded answers and deep_research for broad/multi-part questions. It also says to prefer this over web search, which makes routing unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond those: this is an experimental router that may change live when a candidate is under test, and currently no candidate is active. This helps the agent understand the tool's volatile routing behavior.

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

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

The description is a single coherent paragraph with all sentences contributing useful context: what it is, current state, when to use, and the fallback reassurance. It earns its place, though details like 'same 5,798 tools' and the exact retirement date add minor clutter that could be trimmed without losing core 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?

The description covers purpose, beta status, current runtime state, and usage condition well, while the schema fully documents the question parameter and its aliases. However, there is no output schema and the description only says the response shape is identical to ask_pipeworx, leaving the actual return value unstated. Since the stable sibling could fill that gap, this is a minor omission rather than a critical one.

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

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

Schema coverage is 100%, with all parameters including aliases described in the schema. The description only repeats that the tool has the same arguments as ask_pipeworx, adding no new parameter-level meaning. A baseline of 3 is appropriate because the schema carries the full documentation burden.

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

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

The description clearly states that this is a beta version of ask_pipeworx and an identical universal router with experimental routing improvements. It explicitly distinguishes itself from the stable ask_pipeworx by describing itself as the experimental edge, which removes ambiguity about what this sibling variant does.

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

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

It says directly, 'Use it exactly like ask_pipeworx when you want the newest routing,' providing an explicit condition for selection. It also explains that results are compared against the stable router to decide what merges, clarifying the purpose and relationship to the alternative.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses exactly how the tool behaves: it extracts answers 'using ONLY what the tool result contains,' returns a structured success object with evidence and confidence, and explicitly defines refusal reasons when data cannot answer. It also discloses the extra cost of one LLM call. No annotation contradiction exists.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, output contract, refusal behavior, usage guidance, and cost trade-off. It is front-loaded with the core value proposition and avoids fluff or repetition.

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

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

There is no output schema, so the description correctly carries the burden of explaining success and refusal return shapes, evidence quoting, refusal reasons, and the comparison to ask_pipeworx. Given the tool's complexity and high-stakes context, nothing critical is missing for an agent to invoke it correctly and interpret results.

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

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

Schema description coverage is 100%, and the schema itself documents the single required `question` parameter plus all aliases. The description does not add parameter-level semantics, but it does not need to because the schema is complete. 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 opens with a specific, meaningful purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the tool's function—route, fetch, extract grounded answers with evidence and refusals—and differentiates it from the sibling ask_pipeworx by emphasizing evidence extraction and refusal 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?

Explicit usage guidance is provided: use it 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete high-stakes examples. It also names the alternative, ask_pipeworx, and states a clear preference rule: 'prefer ask_pipeworx for casual lookups.' This is strong routing 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, etc. The description adds context about rate limits via the optional _apiKey parameter and specifies the output fields, which is valuable beyond the annotations. 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 with no filler. The first sentence states purpose clearly; the second specifies return values. All information is relevant and front-loaded.

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

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

For a tool with 4 parameters and no output schema, the description covers the core functionality and return values. It could mention pagination or offset, but offset is described in the schema. Overall adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not elaborate on parameters beyond what the schema provides, but it adds overall context that the tool is for searching datasets.

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 searches the Austin open-data catalogue by keyword, specifies the return values (dataset names, descriptions, resource ids), and hints at integration with austin_query, distinguishing it from siblings like austin_query and austin_recent.

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

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

The description implies usage for finding datasets before querying them via austin_query, providing a clear context. However, it does not explicitly state when not to use this tool or mention alternatives like austin_recent.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. Description adds context about the Socrata endpoint and raw SoQL syntax but does not discuss rate limits or side effects beyond that. Adds some value but limited.

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 three sentences, front-loaded with core purpose, lists clauses, and directs to sibling tools. No wasted words.

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

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

Given 8 parameters and no output schema, description explains the tool's purpose, syntax, and discovery path. Could mention return format, but not essential for this tool type.

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

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

Schema coverage is 100% with descriptions for all 8 parameters. Description adds high-level context (e.g., resource_id format, optional _apiKey) but does not significantly deepen understanding beyond schema.

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

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

Description clearly states it runs a raw SoQL query against Austin open-data resources, specifies resource ID format, and lists supported clauses. It distinguishes from sibling tools austin_datasets and austin_recent by directing users to those for discovery.

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 says to use this tool for SoQL querying and mentions sibling tools for finding resource IDs. It does not provide explicit when-not-to-use guidance, but context is clear.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that it returns newest-first rows and uses friendly names instead of Socrata IDs. Does not detail pagination or error handling, but overall behavior is transparent enough.

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 concise sentences: purpose, usage preference, dataset names, behavior. Each sentence adds unique value with no redundancy. Effectively front-loaded.

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

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

Given 4 parameters, full schema coverage, and complete annotations, the description sufficiently covers the tool's functionality. It tells the agent what datasets are available, how to filter, and when to use an alternative. No gaps with 1 required param and no output schema.

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

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

Schema coverage is 100%. Description adds meaning by mapping dataset names to real-world categories (crime, 311, etc.) and explains the optional SoQL where filter. It clarifies the friendly name concept and that _apiKey is optional for higher rate limits, going 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 retrieves recent records from Austin open datasets, names the specific datasets, and distinguishes it from austin_query by saying 'for anything else use austin_query'. It is a specific verb+resource with sibling differentiation.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' for common queries like 'recent crime in Austin' and instructs to use austin_query for anything else. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, ensuring safety. The description adds extensive behavioral details: low-confidence short-circuits, closed market handling, wide spread warnings, resolution-rule risk, and fan-out specifics. This far exceeds what annotations provide.

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

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

The description is thorough and well-structured with sections, but quite verbose. It front-loads the main purpose and provides examples, but could be more concise without losing clarity.

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

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

Given 3 parameters and no output schema, the description thoroughly covers response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, and resolution risks. It leaves minimal gaps for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining market input formats (slug, URL, question text), depth parameter options, and include_raw semantics, including response size implications.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant Pipeworx data, with specific verb+resource. It distinguishes from siblings by focusing on individual bet research for 'should I bet on X' scenarios, differentiating it from polymarket_edges and polymarket_arbitrage.

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 usage scenarios are provided: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. While no direct exclusions or alternatives are named, the context is clear and covers common use cases.

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

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

Adds significant behavioral context beyond annotations: for companies it pulls latest 10-K data; for drugs, FAERS, FDA approvals, trials. Also explains sorting by primary metric. 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 dense with information but still concise. It is front-loaded with example phrases, though could be broken into smaller sections for readability.

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

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

Covers input (params), behavior (data sources, sorting), and output (paired data + citation URIs). No output schema, but description adequately explains return values.

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 meaning: explains that values are tickers/CIKs for companies and drug names for drugs, with constraints 2-5 items. Provides more detail than schema alone.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs, provides example query phrases, and distinguishes from siblings like entity_profile.

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 to ALWAYS PREFER over sequential single-pack lookups, and the context of comparing multiple entities is well-defined.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: account/auth requirements, decomposition into facets, parallel tool routing, the exact contents of the findings packet, gaps[] behavior, contradictions[], semantic excerpting, and latency expectations. No contradiction with annotations.

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

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

The description is long but dense and well-structured, front-loading the critical account/alternative note before the core behavior. Every sentence adds useful information, though depth-tier details are partially repeated between the opening and the parameter explanation, and the opening paragraph is slightly cluttered. Overall, the length is justified by the tool's complexity.

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

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

Despite having no output schema, the description fully explains what the tool returns: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and excerpted records. It also covers auth, cost tier, latency, sibling routing, and the exact difference from ask_pipeworx. Nothing critical for an agent to invoke and interpret the tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the practical implications of depth values (quick=3 single hop, standard adds gap recovery and contradictions, thorough=6 paid iterative hop), clarifies that the question should be natural language and broad/multi-part, and adds latency context tied to depth. This exceeds 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in one call. It explicitly distinguishes itself from open-web search and names the output (findings packet with evidence, confidence, source, citation, gaps), making it clear what the tool does and how it differs from siblings.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and directly points to the alternative: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' It also explains the depth tiers and when each is appropriate, so an agent can route correctly.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds beyond that by explaining the return format (names, descriptions, schemas with examples) and that results are ready to call directly, providing useful 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?

Description is front-loaded with action and usage context, followed by examples and return details. Each sentence adds value; not overly verbose. Slightly long but well-structured.

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

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

Given no output schema, the description adequately covers what is returned (top-N relevant tools with names, descriptions, schemas). Explains that results are ready to call directly. Does not detail ranking criteria but sufficient for a discovery tool.

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

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

Schema description coverage is 100% with all parameters well-described. The description adds minimal extra meaning beyond schema, primarily explaining the purpose of the query parameter and its aliases. Baseline 3 is appropriate.

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

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

Description clearly states the tool 'Find tools by describing the data or task' with a specific verb and resource. It distinguishes from sibling tools that are task-specific (e.g., austin_query, bet_research) by focusing on discovery of the tool set.

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 says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST... when you want to see the option set'. Provides clear context for when to use, though lacks explicit when-not-to-use or 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?

Even with readOnlyHint and idempotentHint annotations, the description adds substantial context: parallel fan-out, soft-fail behavior, per-source data availability flags, empty-section semantics, and the resolved:false path for private companies. It also accurately describes the interplay of sources without contradicting annotations.

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

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

The description is quite long, but the tool is complex and the length is mostly justified by enumerating sources, return fields, and edge-case behaviors. It is front-loaded with usage examples and the key routing directive, though it could be tightened and broken into structured sections to improve scannability.

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

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

For a tool with no output schema, the description is unusually complete: it explicitly enumerates the response sections, URI format, sorting, fallback behavior, and expected empty results, and it explains what resolved:false means. An agent can correctly invoke this tool and interpret its output without additional context.

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

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

The input schema already documents both parameters thoroughly, including the accepted ticker/CIK/name formats, the enum choices, and that the two enum values behave identically. The description largely restates this rather than adding new parameter-level meaning, so the 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 states a specific verb and resource: it builds a full cross-source profile of a US public company. It also differentiates itself from sibling tools by explicitly preferring it over chaining single-pack SEC/XBRL/news lookups and by naming the specific sources it covers.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also covers valid inputs (ticker, CIK, name) and clarifies expected behavior for private companies, leaving little ambiguity about when this tool is appropriate.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds context about clearing sensitive data and purpose (stale context, done tasks), which goes beyond the annotations. 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 two sentences, both are essential and front-loaded. No unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, and behavioral context completely. 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?

The single parameter 'key' is fully described in the schema (100% coverage). The description does not add additional meaning 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 uses a specific verb 'Delete' and resource 'memory by key', distinguishing it from sibling tools like 'remember' and 'recall'. It clearly states what the tool does.

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

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

The description explicitly states when to use the tool: when context is stale, task is done, or to clear sensitive data. It also suggests pairing with siblings. It lacks explicit 'when not to use' but provides clear positive scenarios.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds behavioral details such as fetching the page, extracting title/description/key links, and outputting standard markdown format. It also states the output is a single text blob, which is helpful 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 three sentences: purpose, process, and use cases. It is front-loaded with the main action, and every sentence adds value. No redundant or unnecessary 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 simple tool with two parameters, no output schema, and comprehensive annotations, the description covers the core functionality and use cases adequately. It could mention limitations like accessibility of URLs, but overall it provides sufficient context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for both parameters ('url' and 'max_links'), so the schema already explains the parameters. The tool description does not add additional parameter semantics beyond what is in the schema, meeting the baseline for high coverage.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, specifying the verb 'generate' and the resource 'llms.txt file'. It explicitly mentions the purpose of helping AI crawlers index sites, making it distinct from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence'.

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

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

The description lists three concrete use cases: getting a client's site indexed, drafting for own project, or auditing a competitor's site. It provides clear context for when to use the tool, though it does not explicitly exclude alternatives or mention 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 provide readOnlyHint, destructiveHint. Description adds specific return fields and default behavior (active only). 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, front-loaded with purpose, no wasted words. Efficiently communicates key information.

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

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

For a simple list tool with one optional parameter, description covers return fields and usage context. No output schema but sufficient for 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%, description does not add meaning beyond what schema already provides for the parameter 'include_inactive'.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Lists return fields and distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Provides explicit guidance on when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Implies alternatives but does not explicitly state 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 are all false, providing minimal safety cues, but the description compensates with rich behavioral details: rate-limiting ('5 per identifier per day'), quota implications ('doesn't count against your tool-call quota'), the claim_token retrieval flow, and team SLA ('reads digests daily'). These are exactly the non-obvious behaviors an agent needs to understand, going far beyond what the annotations state.

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

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

Every sentence in the description serves a distinct purpose: definition, usage, exclusions, formatting rules, token workflow, and operational details. There is no filler or redundancy, and the most critical info (what it does and when to use) appears first. Despite its length, each clause earns its place given the tool's multi-faceted behavior.

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 accounts for all relevant operational aspects: success/failure paths (claim_token generation), retry semantics (passing token later), rate limits, quota impact, response timeframe (daily digest), and scope boundaries. Since there is no output schema, the description fully substitutes for return-value documentation, making it complete for this 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?

Although the input schema covers all parameters (100% coverage), the description adds meaningful usage context: instructing to 'describe the issue in terms of Pipeworx tools/packs' clarifies the message parameter, and 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})' enriches the claim_token semantics beyond the schema's terse definition. This pushes it above the baseline 3.

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

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

The description opens with a specific verb+resource pairing ('Tell the Pipeworx team') and clearly enumerates the feedback types (bug, feature, data_gap, praise). It further distinguishes itself from siblings by limiting scope to 'Pipeworx tools' and explicitly excluding feedback about other MCP servers, making its unique role unmistakable.

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

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

The description gives explicit when-to-use triggers ('returns wrong/stale data', 'wish existed', 'worked surprisingly well') and a direct when-not-to-use exclusion ('if the tool came from a different MCP server... file it with that server instead'). It also clarifies ambiguity by referencing the Pipeworx tool list as the authoritative scope, fulfilling all criteria for usage guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds crucial context: it is self-aggregating from CF analytics-engine, no PII, and cached 5min-1h depending on window. This fully informs the agent of behavior.

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

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

The description is a concise paragraph with a clear headline, three listed use cases, and a final sentence on data source and caching. Every sentence adds value; no redundancy.

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

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

Despite no output schema, the description explicitly states what is returned (top tools, top packs, total call volume) and explains caching and data source. Complete for a simple trending tool.

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

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

Schema coverage is 100% for the single parameter 'window', and the description does not add new information beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it returns top tools, top packs, and total call volume over recent windows, distinguishing it from sibling tools like discover_tools by focusing on what other AI agents are calling.

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 lists three specific use cases (discovering hot data sources, confirming canonical choice, seeing use case alignment), providing clear guidance on when to use the tool, though it does not explicitly mention 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?

Discloses behavioral traits beyond annotations: scanning methods, fill check, semantic anchor, partition filter, and response structure. No contradictions with annotations (readOnlyHint, idempotentHint).

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

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

The description is detailed and front-loaded with the main purpose. While lengthy, every sentence adds value. Slightly too verbose for perfect 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?

No output schema, but the description explains the response fields (gap_pp, suggested_trade, reasoning, etc.) and edge cases (fill check, partition filter). Could be more structured, but adequate given complexity.

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

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

Schema coverage is 100% with descriptions, but the tool description adds significant meaning: examples of event slugs, explanation of topic mode, and how each parameter affects 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?

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from siblings like polymarket_fill_risk, which is mentioned for custom sizing.

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

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

Explicitly explains when to use no args (trending scan), event (single event slug), and topic (cross-event scanning). Includes a fill check that says when not to trade. Could more explicitly contrast with polymarket_edges, but references polymarket_fill_risk.

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 a safe, non-destructive tool. The description adds significant behavioral detail: caching (1h at KV level), response structure (by_segment with diagnostics), Fed bet exclusion, and the 24h-move warning. This fully discloses behavior beyond annotations without contradiction.

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

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

The description is front-loaded with the core purpose and well-structured with segments. However, it is verbose and could be more concise by reducing duplication of parameter descriptions already in the schema. Despite this, every sentence provides useful context.

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

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

Given the complexity of 9 parameters and no output schema, the description thoroughly explains the response structure (by_segment, diagnostics), caching, and edge cases (Fed bets). It leaves no critical information gaps for an AI agent to effectively use the tool.

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

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

With 100% schema coverage, the description still adds value by explaining the strategic use of knobs (e.g., min_liquidity, max_spread_pp) and providing concrete examples (e.g., 'Set to 5000 to drop thin-book opportunities'). This goes beyond the schema's descriptions, enhancing agent 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: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market prices. It distinguishes itself by detailing three specific model families and their segments, making the resource and action unambiguous.

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

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

The description provides a clear use case ('what should I bet on today') and explains the model families and parameter knobs. However, it does not explicitly state when to avoid this tool or compare it with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which would help an agent choose 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 provides extensive behavioral transparency beyond the annotations, detailing the response structure (tracked, expired, snapshot_dates), explaining edge cases like negative values and cache-miss gaps, and noting limitations on history depth and decay calculation. 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 well-structured and front-loaded with the key purpose, but it is somewhat lengthy. Every sentence is informative and contributes to understanding, earning its place given the complexity.

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

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

Despite the absence of an output schema, the description thoroughly explains the response structure and limitations, making it contextually complete for the agent to use the tool effectively. It covers all necessary details.

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

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

Schema description coverage is 100%, and the description only reiterates default values and constraints already present in the schema (e.g., days default 14, max 30; window default '1wk'). No new semantic information is added beyond the schema.

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

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

The description clearly states the tool's purpose as providing edge persistence and decay telemetry, answering the specific question about edge age and trend. It implicitly differentiates from the sibling tool 'polymarket_edges' by focusing on time-series analysis built from snapshots.

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

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

The description implies usage for edge decay analysis but does not explicitly state when to use or not use this tool. It fails to mention alternatives or provide exclusion criteria, leaving the agent to infer usage context.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, etc. The description adds detailed behavioral context: walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, and for basket mode explains forced_directional_risk and thin_legs. 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 fairly long but well-structured: starts with purpose, then explains modes, defaults, return values, and usage warning. Every sentence adds value; minor conciseness improvement possible but front-loading is effective.

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

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

No output schema exists, but the description thoroughly explains return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill, thin_legs, max_clean_notional, forced_directional_risk for basket). Covers the complex risk scenario comprehensively.

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

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

Schema description coverage is 100%, but the description adds significant meaning: size_usd interpretation varies by mode (max spend on buys vs target proceeds for single-market, settlement notional for basket), side defaults to buy_yes in single-market and auto in basket, and market/event are mutually exclusive. This goes well 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 it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with two modes (single-market and basket). It explicitly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a prerequisite risk check.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround on thin books is not capturable, partial fills convert arb to unhedged position) and provides context on required inputs (market or event).

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations: it discloses the token-overlap matching algorithm, the meaning of compatibility_codes, that unknown metric_type/match_subtype legs are never paired, that temporal_alignment null means 'could not be computed' rather than aligned, and that spreads are gross of Kalshi fees. This is rich behavioral disclosure with no contradiction to 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-organized with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS, Codes), and nearly every sentence carries operational value for a complex tool. It is somewhat dense and repeats concepts between the safety-codes list and the per-entry flags list, so it is not maximally concise, but the structure helps an agent parse it.

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 there is no output schema, the description thoroughly documents the response contract: leg-by-leg prices, top_spreads_pp, compatibility fields, per-entry flags, skipped counters, temporal_alignment semantics, and the fees caveat. It also warns about interpretational traps such as pairing_unverified and pre-mapped ≠ tradeable, making it complete for correct invocation and result interpretation.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the property descriptions: it lists the exact 10 topic values, explains that explicit ticker/slug overrides the topic-mapped side, and clarifies that both modes run the identical matcher. This makes the interaction between parameters and modes much clearer than the schema alone.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, which is specific and useful. It lacks an explicit verb like 'calculates' or 'returns,' and while it distinguishes itself from other Polymarket-only siblings, it doesn't explicitly differentiate itself from the closely named sibling polymarket_arbitrage.

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 internal usage guidance: it explains TWO MODES, when to use topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug, and warns that pre-mapped topics often return compatibility warnings. However, it does not explicitly state when to choose this tool over sibling tools like polymarket_arbitrage or polymarket_edges, so the cross-tool usage guidance is only implied.

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

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

Annotations indicate readOnly, idempotent, non-destructive. The description adds behavioral details: scoping by identifier (anonymous IP, BYO key hash, account ID) and the dual behavior of retrieving a specific key vs listing all keys. No contradictions.

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

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

The description is concise with four sentences, each serving a clear purpose: function, use case, scoping, and complementary tools. No redundant 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 simplicity of the tool (1 optional param, no output schema, annotations present), the description covers essential aspects: purpose, usage, scoping. It does not mention output format or error cases, but for a retrieval tool, it is adequate.

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

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

The single parameter 'key' is fully described in the schema (100% coverage). The description adds value by explaining that omitting the key lists all saved keys, which is beyond the schema's description.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys. It is specific about the verb (retrieve/list) and resource (saved values), 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 recall (to look up context without re-deriving) and mentions pairing with remember/forget. However, it does not explicitly contrast with other sibling tools, though the use case is clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds behavioral details: mark_read flag makes events read for subsequent calls, and the feed is also available via HTTP endpoint. No contradictions; adds value beyond annotations.

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

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

The description is efficient, with 4 sentences that front-load the main purpose and then detail key parameters and usage notes. No redundancy; each sentence contributes 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?

No output schema, but description covers return fields (source, citation_uri, raw payload) and side effects (mark_read). Given 5 optional parameters and good annotations, the description is fairly complete for a read-only tool.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. Description adds meaning by explaining mark_read behavior (flags as read), unread_only filtering, and example type filter ('sec_8k'). This enriches the schema information.

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

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

The description clearly states it pulls fired events from subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes from general search tools but does not explicitly compare to siblings like 'list_subscriptions'. Purpose is clear and specific.

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

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

Provides guidance on filtering by type, since, mark_read, unread_only. Mentions polling works fine and notes an alternative endpoint for scripts/dashboards. Lacks explicit when-not-to-use or alternatives among siblings, but the context is helpful.

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 rich behavioral details: fanning out to SEC EDGAR, GDELT→GNews fallback (with rate-limiting note), USPTO sunset caveat, and supported `since` formats. 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 moderately long but well-structured with quotes for examples and a clear separation of concerns. It front-loads the purpose and usage, though some redundancy could be trimmed. Still effective.

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

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

Given no output schema, the description sufficiently previews the return structure ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also addresses the complexity of multiple data sources, fallback logic, and input formats, making the tool fully understood.

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

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

Schema coverage is 100% (all params described), so baseline is 3. The description adds value by explaining `since` formats (ISO vs '7d') with examples, and clarifying `value` accepts ticker or CIK. This provides 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 provides specific verbs and resources: 'change feed for a company', with examples like 'What's new with X'. It explicitly distinguishes from the sibling 'entity_profile' tool, making the purpose crystal clear.

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

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

The description gives direct guidance: 'Use entity_profile instead when you want the static profile'. It also provides example queries and explains when to use relative vs ISO dates, offering comprehensive usage context.

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

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

Annotations already provide idempotentHint=true (safe to repeat), destructiveHint=false, and readOnlyHint=false (write). The description adds valuable behavioral context: key-value storage, identifier scoping, persistence differences between authenticated (permanent) and anonymous sessions (24 hours). 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?

Four sentences, no fluff. The most critical information (purpose, when to use, behavior) is front-loaded. Every sentence adds value, from examples to pairing with related tools.

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, no output schema), the description completely covers its purpose, usage context, behavioral nuances, and relationship to sibling tools. No gaps remain for an agent to misinterpret.

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

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

Schema coverage is 100%, so the schema already documents both parameters thoroughly. The description reinforces the key-value pair concept but does not add significant meaning beyond what the schema provides (which already includes examples for 'key' and value is 'any text'). 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 starts with a specific verb ('Save data') and resource ('the agent will need to reuse later'), clearly stating its purpose. It provides concrete examples (resolved ticker, target address, user preference, research subject) and distinguishes itself from sibling tools by explicitly pairing with '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?

The description explicitly states when to use ('when you discover something worth carrying forward') and provides guidance on scope ('across this conversation or across sessions'). It also contrasts with sibling tools ('Pair with recall to retrieve later, forget to delete'), meeting the high standard for usage guidelines.

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, idempotent, and non-destructive, and the description substantially builds on that: it explains internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguous-name handling via figi_candidates, explicit unresolved fields, and source-labeled identifiers. This is far beyond the annotation baseline.

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

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

The description is long and dense, but nearly every clause adds operational detail. It is front-loaded with the core purpose and the 'use FIRST' directive; the extended parentheticals about bonds and ISIN resolution are verbose yet high-value. It is arguably overlong, but not wasteful.

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 two distinct entity types, the description covers input format, supported types, identifier sources, ambiguous results, unresolved outputs, and dependency failures. The only minor omission is a precise output shape, but the behavior is described thoroughly enough for an agent to call it correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds exceptional value: concrete examples for both types, guidance to pass the entity name only rather than the full noun phrase, accepted identifier formats, and behavior for ambiguous matches. It meaningfully enriches both parameters.

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

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

The description opens with concrete natural-language patterns and states the core action: resolve a user-spoken NAME to canonical/official identifiers. It clearly distinguishes itself as the first-stop tool for name-to-ID needs and differentiates from siblings like entity_profile or validate_claim.

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 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use context. It does not enumerate alternatives or say when not to use the tool, but the supported types and graceful-degradation notes fill most practical gaps.

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

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

Annotations provide readOnlyHint, idempotentHint. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density per entity. 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?

Four sentences, front-loaded with main action, no waste. Every sentence adds value.

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

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

Given annotations and schema coverage, description covers purpose, behavior, and output format. No output schema, but output is described. Nearly 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 coverage is 100%, so baseline 3. Description adds minimal extra meaning: first entity treated as 'subject'. No further parameter details beyond schema.

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

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

Description states it compares AI visibility across multiple entities side-by-side, uses ai_visibility_check, ranks by score, and surfaces most/least recognized. Clearly distinguishes from sibling ai_visibility_check which is single-entity.

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 says useful for competitive AI-marketing audits with an example question. Implies for single-entity use ai_visibility_check, but no explicit when-not-to-use or alternatives beyond that.

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 details behavioral traits beyond annotations: it fans out across deps.dev and bundlephobia, bundlephobia's first measurement may take 5-30s, partial failures degrade gracefully with sources_failed listed. Annotations already indicate readOnly, idempotent, non-destructive. No contradiction.

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

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

The description is detailed but every sentence provides essential information. It is front-loaded with the main purpose and structured clearly, though slightly verbose. Could be trimmed slightly but not unnecessarily.

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

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

Despite no output schema, the description fully explains the return structure (summary block, advisories, links, alternative versions) and covers edge cases like partial failures and timing. Complete for a composite tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra context: scoped packages are accepted for 'package' and version defaults to latest when omitted, which adds value beyond schema.

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

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

The description clearly states the tool's purpose as a composite check for npm packages covering license, advisories, version history, and bundle size. It explicitly answers the question 'should I add this npm package?' and distinguishes itself from siblings by noting NPM ecosystem only in v1.

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 is provided: use when an agent asks about safety, popularity, or size of an npm package. It also states what not to use (other ecosystems like PyPI, Maven are handled by deps.dev directly) and explains partial failures.

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 rich detail beyond annotations: embedding model, window size, char cap, truncation flag, and offset 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?

Two focused sentences with technical note; every sentence earns its place, no fluff.

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

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

Completely describes return values (passages with offsets and scores), constraints, and pairing with sibling tool, despite no output schema.

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

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

Adds meaning beyond schema with examples and behavioral constraints (max chars, default limit, natural-language query examples).

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

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

Clearly states semantic search inside a fetched record, with specific examples and explicit distinction 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?

Explicitly says when to use (record too big), pairs with alternative tool, and mentions truncation behavior and cap.

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

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

Annotations indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: OAuth requirement, type-specific parameters, delivery constraints (SMS cap, webhook auto-disable), and the always-on feed. No contradictions with annotations.

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

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

The description is detailed and front-loaded with the purpose, but each sentence adds value. Slightly verbose in the delivery section, but overall well-structured for a complex tool.

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

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

For a tool with 3 parameters and no output schema, the description covers all aspects: purpose, requirements, types, parameters, delivery options, constraints, and return value. It is complete and contextual.

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 greatly expands on each parameter with concrete examples, required fields, and additional constraints (e.g., webhook signing, SMS verification). It adds meaning beyond the schema definitions.

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

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

The description clearly states the tool creates a 'proactive monitoring subscription to a live-data event stream' and returns a subscription ID. It lists supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explicitly requires a Pipeworx OAuth account, noting that anonymous and BYO accounts cannot persist subscriptions. It implies use for creation versus listing/unsubscribing, though it does not explicitly state 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 signal readOnly, openWorld, idempotent, non-destructive. Description adds value by detailing the return content (category-bucketed examples, exact tool+argument shape) and the effect of the optional topic parameter, which goes beyond annotations.

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

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

The description is informative but somewhat long, listing many example phrasings and categories. It is front-loaded with alternatives, but some repetition could be trimmed. Balanced for the amount of 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 no output schema, the description sufficiently explains the return format (category-bucketed example questions with tool shapes) and the categories covered. It covers the essential use cases (new user, learn 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 topic parameter with description. Description adds context: lists focus areas explicitly and explains that omitting topic gives a cross-category spread. This adds meaning beyond the schema entry.

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

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

The description uses specific verbs ('returns', 'use', 'learn') and resource ('category-bucketed example questions with tool calls'), clearly stating it's an onboarding entry point. It distinguishes from siblings by focusing on getting started and understanding what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides call patterns (no args vs topic). Could include when not to use, but the guidance is clear.

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

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

The description explains that the row is deactivated, not deleted, and that historical events remain available via 'recent_alerts'. This adds behavioral context beyond the annotations (which indicate non-destructive and idempotent). No contradiction with annotations.

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

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

Two short sentences, front-loaded with the action, and every word adds value. No wasted text.

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

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

For a simple one-parameter tool with good annotations, the description covers purpose, constraints, and behavioral details completely. 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% for the single 'id' parameter, and the schema already describes it as 'Subscription id (uuid) returned by subscribe.' The description adds no additional semantic detail beyond the schema.

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

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

The description clearly states the action 'Cancel a subscription by id' and contrasts with sibling tools like 'subscribe' and 'list_subscriptions' by specifying the operation and resource.

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

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

It provides a key usage constraint: 'Ownership is enforced — you can only cancel your own subscriptions.' This tells the agent when it can and cannot use the tool, though it doesn't explicitly exclude alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds crucial behavioral details: the SEC EDGAR fast path with 'exact percent-delta math', the fallback pipeline for any other claim, and important caller guidance distinguishing 'could_not_verify' (error during verification) from 'unsupported' (no source found). It even describes the error structure and warns not to present 'could_not_verify' as evidence. This is rich, non-redundant 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 every sentence adds value. It starts with user-intent phrases, states the primary use case, explains the two processing paths, lists return values, and ends with a critical caveat and efficiency claim. The structure is logical and front-loaded, with no wasted words or tautology.

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

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

Given the tool's complexity (two pathways, multiple verdicts) and the absence of an output schema, the description adequately explains return values: a verdict (with the full enum), the actual value with a pipeworx:// citation, and reasoning. It also covers failure semantics ('could_not_verify' vs 'unsupported') and explicitly states it replaces multiple sequential calls, providing full operational context.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaning to 'tolerance_pct' by explaining how it overrides the claim's implied tolerance, setting defaults, and giving a specific use case ('set 1–2 for hallucination detection'). The claim parameter is illustrated with naturally formatted examples. This enrichment goes beyond the schema, though the schema already handles the basics.

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 function with specific verbs: 'verify the claim that…', 'confirm or refute', and accurately describes it as 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by covering both company-financial claims via SEC EDGAR and other factual claims via a grounded pipeline, positioning it as a comprehensive fact-checking tool.

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

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

The description explicitly states when to use it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It differentiates from alternatives by noting it 'Replaces 4–6 sequential calls' and provides clear routing rules (company-financial vs. other claims). However, it does not name sibling tools or explicitly state when not to use it, so it falls short of a 5.

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