Inegi

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

Discloses default model, cost implications for Anthropic ('BYO key — you pay Anthropic directly'), and return structure ('per-model {score, confidence, signals, raw_response} + combined view'). Consistent with annotations (readOnlyHint, openWorldHint, 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?

Five well-structured sentences, front-loaded with core purpose, no wasted words, includes both behavioral and practical details.

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

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

Covers all aspects: purpose, parameters, return format, usage scenarios, pricing side-effect. No output schema but return fields listed explicitly. Complete for a 4-parameter 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. Description adds value by clarifying default behavior for 'models' parameter ('Default model is Workers AI Llama-3.3-70b (free)').

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

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

States explicit purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' Clearly distinguishes from siblings like entity_profile, deep_research by focusing on AI visibility scoring.

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 clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Lacks explicit when-not or direct sibling alternatives, but context is strong enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond annotations: internal routing across thousands of tools, automatic argument filling, stable pipeworx:// citation URIs, and a default grounding strictness level with a 'grounded' variant. It leaves out failure modes and latency, but adds substantial 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 front-loaded well with the most critical content, but it is visibly bloated: the block 'For questions about a single entity, use entity_profile... deep_research instead' appears twice verbatim, and the grounding/news framing is repeated in multiple forms across the tail. Not every sentence earns its place, violating the conciseness standard.

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 routing tool with one required parameter, rich annotations, and no output schema, the description covers the essential ground: domain scope, trigger phrases, examples, sibling exclusions, citation return format, and grounding behavior. It is missing only minor details like what happens when routing fails or expected latency, which keeps it just short of complete.

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

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

Schema description coverage is 100% — the schema documents the question parameter and all five aliases (q, text, input, query, prompt). Per the high-coverage baseline, the description need not repeat param details; it adds modest value by modeling how to phrase questions through trigger phrases and examples, but nothing beyond what the schema already conveys about the single required parameter.

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+resource: it routes natural-language questions to the right one of 5,798 tools across 1,517 verified sources and returns structured answers with citation URIs. It is explicitly differentiated from siblings like recall (memory), entity_profile (single entity), deep_research (complex multi-hop), and ask_pipeworx_grounded (stricter grounding), so an agent can tell them apart immediately.

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?

Gives an explicit preference rule ('PREFER OVER WEB SEARCH'), trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), concrete examples, and a default strategy ('START HERE for most questions'). It also states exclusions with named alternatives: use recall for stored facts, entity_profile for single entities, and deep_research for multi-hop reasoning — this is exemplary 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, idempotentHint, and non-destructive behavior, and the description adds substantial context beyond them: behavior is variable ('candidate routing improvements enabled live whenever one is under test'), the current state is identical to stable ('No candidate is active right now... this currently matches ask_pipeworx exactly'), and it fully works rather than degrading ('Falls back to nothing — this IS a full working router'). This gives the agent an accurate model of a beta whose behavior may drift without warning. 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?

Five sentences, each earning its place: identity, current status, usage direction, comparison purpose, and fallback reassurance. The beta/current-state/usage facts are front-loaded before the comparison-to-stable detail. Ends with a slightly redundant restatement ('this IS a full working router, just the experimental edge'), but overall it is dense without bloat.

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 is complete for a router with a trivial all-alias schema: it covers what the tool is, its current behavioral state, when to use it, and what remains constant ('same response shape', covering the absent output schema). The only notable omission is guidance on what an agent should do differently if a candidate were active, since response/routing behavior would then diverge from ask_pipeworx without warning.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (question plus five aliases). The description adds only that the arguments match ask_pipeworx ('same arguments'), which is a useful cross-reference but not per-parameter semantic detail. Baseline 3 is appropriate since structured fields carry the load.

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, identifiable purpose: a beta version of ask_pipeworx that is an identical universal router over the same 5,798 tools with the same arguments and response shape. It clearly differentiates itself from the sibling ask_pipeworx (stable router) and ask_pipeworx_grounded by positioning itself as the experimental edge. The verb 'routes' is implicit but concretely established by 'universal router' plus the exact tool/argument/response inventory.

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 names the alternative and the selection condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also adds that results are compared against the stable router to decide merges, which tells an agent the experimental context. It stops short of stating an explicit when-not condition (e.g., 'use ask_pipeworx for reproducible stable results'), so it is clear but not fully exclusionary.

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, the description discloses rich behavioral detail: refusal modes with specific reasons, evidence as a verbatim quote, verbatim-only extraction, and refusal when data does not directly answer. It also explains the extra LLM call cost. The described read-only, non-destructive behavior aligns with the annotations and adds significant context.

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

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

The description is dense but every sentence earns its place: it front-loads the core purpose, then adds behavioral guarantees, return/refusal shapes, use cases, and cost trade-off. There is no filler or repetition, and the structured examples are easy to parse.

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

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

Despite having no output schema, the description fully specifies the success response shape and all refusal reason values. It also covers when to use the tool, how it differs from the sibling alternatives, and its cost. For a question-answering tool with simple, fully documented parameters, this is 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%, and the schema fully documents the single required question parameter with aliases. The description does not add new parameter-level meaning, but it doesn't need to because the schema already carries that weight, so baseline 3 is appropriate.

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

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

The description clearly defines this as a hallucination-resistant, grounded answer mode for high-stakes reads, and states that it extracts answers using only the tool result. It explicitly differentiates itself from ask_pipeworx by describing the same routing but stricter answer extraction, so an agent can distinguish it from the sibling tools.

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

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

The description explicitly says when to use this tool: whenever an answer will be quoted, cited, or acted on, and when the agent must not invent facts. It also gives a direct exclusion, preferring ask_pipeworx for casual lookups, and discloses the extra LLM call cost, which helps the agent make a cost-aware choice.

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. Description adds extensive behavioral details: how the tool resolves markets, classifiers, fan-out, response shapes, safety mechanisms (low-confidence short-circuits, closed market handling), resolution-rule risk, and parent event extraction. It goes far beyond annotations in explaining operational 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?

Description is long but densely packed with necessary information. It is front-loaded with purpose and uses clear headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) to structure content. While every sentence adds value, the length could be trimmed slightly without losing substance; however, it remains appropriate for the tool's complexity.

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

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

The description comprehensively covers all aspects of the tool: input parameters, response shapes (with field-by-field explanations), edge cases (low confidence, closed markets, wide spreads), and safety warnings. Despite lacking an output schema, the description compensates fully, making it complete for agent decision-making.

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

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

Schema coverage is 100%, baseline 3. Description adds significant value: for 'market' it explains acceptable inputs (slug, URL, question text); for 'depth' it defines quick vs thorough; for 'include_raw' it clarifies size implications and use cases. This context enhances parameter understanding far 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?

Description starts with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools by providing explicit usage examples and classifiers, making the purpose unambiguous.

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

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

Explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't explicitly list when not to use or name alternatives, the context and sibling list imply boundaries, making guidance clear but not exhaustive.

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 and idempotentHint. The description adds behavioral details: handles off-calendar fiscal years, returns sorted data by primary metric, includes citation URIs, and works in one parallel call. 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 a single dense paragraph that efficiently conveys triggers, behavior, data sources, and output. Could be slightly improved with bullet points for readability, but it remains concise and front-loaded with 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?

Given no output schema, the description adequately explains returns ('paired data + pipeworx:// citation URIs per entity'). Coverage of purpose, usage, parameters, and output is complete for a tool with simple inputs and clear behavior.

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 description adds significant meaning: clarifies enum values (company/drug) with specific data sources, gives examples (tickers/CIKs for company, names for drug), and explains max/min items. This enriches the schema without redundancy.

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 comparisons of 2-5 companies or drugs, with specific data sources (SEC EDGAR for companies, FAERS for drugs). Example queries are given, and it distinguishes from sibling tools like entity_profile which do single-entity lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8-15 sequential lookups, giving clear context for when to use this tool over 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 massively exceeds what the annotations (readOnlyHint, openWorldHint, idempotentHint) already provide. It discloses authentication and cost requirements, latency bounds (15–60s, ~90s for thorough), the decomposition-and-parallel-routing execution model, the exact return packet shape (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), a 'never invented' guarantee for missing facets, and semantic (not head-truncated) excerpting of large records. 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?

Dense but zero-waste: the most operationally critical constraint (account required, fallback tool) is front-loaded, and every subsequent sentence adds new technical or behavioral information — the NOT-open-web clarification, routing mechanics, return format, depth semantics, citation fetchability guarantee, contradiction behavior, excerpting policy, and latency. No filler or restated schema content.

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

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

For a high-complexity tool (3 depth modes, multi-hop iteration, auth tiers, 5,798 backing tools) with no output schema, the description is remarkably complete. It covers prerequisites, fallback, execution model, return format in detail, citation semantics, gap handling, retry/iteration behavior, and performance expectations. Nothing an agent needs to call it correctly or interpret its results is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the execution-flow consequence of each depth value ('multi-step questions resolve in one call', 'chases the best leads from the first pass'), correlating depth with the paid tier, and providing concrete example questions for the question parameter. This is meaningful added context on top of an already-detailed schema.

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

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

The description states a precise verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call'. It explicitly distinguishes itself from open-web search ('this is NOT open-web search') and from the sibling ask_pipeworx ('For a single lookup use ask_pipeworx instead'), so an agent cannot confuse it with any of the 32 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?

Gives explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples, 'For a single lookup use ask_pipeworx instead', and a hard prerequisite with fallback: 'If you are not signed in, use ask_pipeworx instead'. The account and paid-tier constraint is front-loaded, so an agent can route correctly before invoking.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining that the tool returns top-N relevant tools with names, descriptions, and full input schemas, and that results are ready to call directly—information not present in annotations.

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

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

Two sentences, front-loaded with purpose and usage context. No redundant information; every word is meaningful.

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

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

Despite no output schema, the description explains what is returned (top-N tools with names, descriptions, schemas) and that results are immediately callable. Given the tool's discovery purpose and the rich input schema, it is 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% with descriptions for all 6 parameters. The description reinforces that 'query' accepts natural language and provides example domains, adding context beyond the schema. While schema already does heavy lifting, the description's examples and alias mention add slight value.

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

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

The description specifies a clear verb ('find tools'), resource ('tools by describing the data or task'), and differentiates itself by listing numerous domains (SEC filings, FDA drugs, etc.). It also states that results include full schemas, making the tool distinct from its 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?

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set', providing clear guidance on when to use this tool versus alternatives. It implies not to use when you already know the specific tool needed.

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

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

Annotations already mark the tool as read-only and non-destructive, and the description adds substantial behavioral detail about the fan-out, sources_used/sources_failed semantics, empty-section meaning ('real no data, not a bug'), and the private-company resolved:false response. No contradiction with annotations exists.

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

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

The description is dense and long, but it is front-loaded with examples and a clear statement of purpose, and it includes a logical progression from what it does to what it returns. Some redundancy exists, such as repeating type/value interchangeability, but the extra detail on sources, URIs, and failure semantics earns its place given 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?

There is no output schema, so the description carries the full burden of explaining return values. It lists the key response fields (cik, company_name, resolved_from/to, recent_filings with URIs, fundamentals, sources_used/failed, LEI) and explicitly covers empty-section and private-company behaviors, making the tool's behavior fully predictable for an agent.

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

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

The input schema already provides 100% coverage for both parameters including ticker/CIK/name formats and the interchangeability of type. The description largely restates what the schema says, though it adds the useful clarification that both type values accept the same value shapes; this is helpful but not a major semantic expansion.

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 user-phrase examples and immediately states the core function: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes this from chaining single-source lookups and from sibling tools like compare_entities or resolve_entity by emphasizing the holistic, all-in-one nature.

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

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

It explicitly says to prefer this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view, and provides precise input forms (ticker, CIK, company name). It also sets expectations for edge cases like private companies, telling the agent what result shape to expect rather than assuming failure.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds behavioral context about clearing stale or sensitive data, but does not elaborate on irreversibility or other traits. No contradiction with annotations.

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

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

Two sentences concisely convey purpose and usage guidelines, plus a pairing suggestion. No fluff; every sentence earns its place.

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

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

For a simple destructive tool with one required parameter, the description fully covers when to use and what it does. No output schema needed; agent can correctly invoke based on provided information.

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

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

Schema description coverage is 100% with a clear description for 'key'. The tool description adds no additional semantics beyond restating 'by key'. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the verb 'Delete' and resource 'memory by key', leaving no ambiguity about the tool's function. It also distinguishes itself from sibling tools like 'remember' and 'recall' by focusing on deletion.

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

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

Explicitly provides when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with 'remember' and 'recall', offering guidance on related tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown format—affirming and complementing the 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?

Three sentences, each with purpose: first states what it does and for whom, second explains the process, third lists use cases. No redundancy, front-loaded with core action.

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

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

With 2 parameters, good annotations, and no output schema, the description explains the output format and audience. It covers the tool's role in AI indexing contexts. Could mention link count limit explicitly, but overall sufficient.

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

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

Schema covers both parameters with descriptions (url required, max_links with default and max). The description doesn't add extra semantics beyond what the schema provides; it mentions the overall process but not parameter specifics. Baseline 3 is appropriate given 100% schema coverage.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, detailing the process (fetch, extract, emit) and target audience (AI crawlers). It distinguishes itself from sibling tools by specifying its unique output format and use case.

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

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

Description provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. While it doesn't list when not to use, the examples cover typical scenarios, offering clear 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, idempotentHint, and destructiveHint=false, which the description does not contradict. The description adds context about the shared API token and the ability to return full history, but no additional behavioral traits beyond what annotations already convey.

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

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

The description is concise, front-loaded with the core purpose (fetch indicator), and includes only essential additional context such as the banxico note and ID discovery guidance. Every 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?

Given the tool's simplicity (fetching indicators with rich schema), the description adequately covers the main functionality, return options (latest or full history), and important cross-references to alternative sources. Lack of output schema is offset by the straightforward nature of the operation.

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 covers 100% of parameters with detailed descriptions, including area codes and source options. The description does not add new parameter semantics beyond the schema, but it reinforces the use case with an example ID and the note about the banxico alternative.

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 fetches INEGI indicators by numeric ID at a chosen geographic level, describes itself as an 'escape hatch' for the full Banco de Indicadores, and lists example domains (GDP, employment, etc.). This is a specific verb+resource scope that distinguishes it from sibling tools like inegi_population.

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

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

The description explicitly advises against using this tool for Mexico inflation, interest rates, and exchange rates, directing the agent to the banxico pack instead. It also provides guidance on finding indicator IDs via INEGI's Constructor de consultas.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds 'Returns the value with its reference year', but little beyond that.

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. 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, it mentions return value and reference year. Covers purpose, granularity, and usage preference. Adequate for a simple 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?

100% schema coverage, so baseline 3. Description does not add extra meaning beyond the schema's parameter descriptions.

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

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

Clearly states it retrieves total population of Mexico at national, state, or municipality level. Distinguishes from sibling tools like inegi_indicator.

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

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

Explicitly advises preference over web search for population queries, and highlights INEGI's geographic detail. Does not explicitly state when not to use, 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 declare readOnly and non-destructive. Description adds return field details and the effect of the include_inactive parameter.

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

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

Two concise sentences, front-loaded with purpose and return fields, followed by usage guidance. No wasted words.

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

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

For a simple list tool with one optional param and no output schema, the description adequately covers return fields and usage. Could mention pagination or limits if applicable, but not required.

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

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

Schema coverage is 100%, with the parameter description in schema. Description mentions the parameter's effect but adds no new semantics 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?

Clearly states 'List the caller's active subscriptions' with specific return fields. Distinguishes from sibling tools like subscribe 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?

Explicitly says to use for review before adding more subscriptions or to find an id to cancel. Provides clear 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?

The description goes far beyond the annotations, disclosing rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), workflow ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), and contextual rules ('don't paste the end-user's prompt'). This is rich behavioral disclosure that annotations alone do not provide.

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

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

The description is long but every sentence adds meaningful information: purpose, usage, exclusions, workflow, rate limits, and cost. It is front-loaded with the primary action and structured logically. No fluff or redundancy.

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

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

With no output schema, the description fully explains return behavior: 'Filing without an account returns a claim_token; pass it back later ... to read whether it was fixed and what changed.' It also covers rate limiting, quota, and usage context, making it complete for a feedback tool with four optional parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics by explaining the claim_token workflow and giving guidance for the message field ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This adds value beyond the schema's per-parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes the tool from siblings by focusing on feedback for the Pipeworx connection specifically. It also names concrete use cases (bug, feature/data_gap, praise), leaving no ambiguity about its purpose.

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

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

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

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by disclosing data source (CF analytics-engine), no PII, and caching duration (5min-1h), which are 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?

Description is concise (5 sentences), front-loaded with purpose, followed by use cases, then technical details. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description specifies return elements (top tools, packs, call volume) but does not define 'top' precisely (e.g., by count or ranking). However, for a trending tool with simple parameters, this is largely sufficient.

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

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

Schema coverage is 100% and the description adds contextual meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches the enum choices beyond the schema.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a recent window, specifying the resource ('what other AI agents are calling on Pipeworx') and verb ('trending'). It is distinct from sibling tools.

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

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

The description explicitly lists three use cases and explains when to use different windows (shorter for hot trends, longer for steady-state). No exclusions or alternatives are mentioned, but the context is clear.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, showing safe behavior. The description adds substantial behavioral context: details on monotonicity checks, partition-sum logic, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and fill check using CLOB depth. 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 comprehensive but somewhat dense with technical jargon (e.g., monotonicity violations, Jaccard similarity, CLOB depth). It is front-loaded with the purpose and well-structured, but could be slightly more concise. Still, every sentence provides value.

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

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

Given the tool's complexity (no output schema, detailed logic), the description covers purpose, parameter semantics, behavioral details, and response structure. It also references related tools (polymarket_fill_risk for custom sizing). Complete and sufficient for correct usage.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond the schema: explains that event accepts slugs or full URLs, topic is a seed question, and details what each mode does and what the response includes. This adds significant value.

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

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

The description clearly states the verb ('Find arbitrage opportunities') and resource ('Polymarket'). It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique approach (monotonicity violations + partition-sum checks). The different modes (trending scan, event, topic) are also clearly defined.

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

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

The description provides explicit guidance on when to use each argument: no args for trending scan, event for a specific market, topic for cross-event scanning. It recommends event mode for specific markets. It does not explicitly state contraindications, but the context is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint=true, indicating safe usage. The description elaborates extensively, explaining the five model families, response segments, diagnostics, caching behavior, and edge calculation details (e.g., slippage, 24h-move warning). 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 verbose with technical details but is structured: purpose first, then model families, response format, and knobs. While every sentence adds value, the length may overwhelm an agent; a more condensed version would improve conciseness.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is complete. It covers the return structure (by_segment, diagnostics), explains how to interpret fields like kelly_fraction and edge_pp_net, and describes all filter knobs. An agent can confidently select and invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema, such as practical usage tips for slippage_pp, explanation of min_partition_leg_kelly's distinct behavior, and examples for min_liquidity. This raises the score to 4.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' and explicitly links it to the 'what should I bet on today' use case. It distinguishes from sibling tools by detailing its unique model families and response structure.

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

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

The description provides clear guidance on when to use the tool ('agents discover opportunities without paging hundreds of markets') and describes tradeable-edge knobs and filters. However, it does not explicitly mention alternative tools or 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?

The description adds significant behavioral context beyond annotations: data comes from daily snapshots, gaps mean no scan, decay uses daily closes, history bounded by 60-day TTL, and detailed response format. Annotations already indicate read-only, idempotent, non-destructive, and the description does not contradict.

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

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

The description is well-structured with a clear purpose statement, response format breakdown, and limitations. It is front-loaded with the key question. While slightly long, each 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?

Since there is no output schema, the description fully explains the return values (tracked, expired, snapshot_dates) with field meanings. It also covers limitations and data sources, making it complete for the tool's complexity.

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

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

Schema coverage is 100% for both parameters. The description adds context to the window parameter by explaining it as 'snapshot family' and the days parameter with default and max. It clarifies the meaning 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 provides edge persistence and decay telemetry from daily snapshots. It distinguishes from the sibling tool polymarket_edges by focusing on historical persistence, and explains the key insight that a fresh wide edge differs from an old one.

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

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

The description explains when to use the tool: to answer how long an edge has existed and whether it is shrinking. It provides context about the difference between fresh and old edges, but does not explicitly state when not to use it or compare it to alternatives.

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

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

Discloses key behavioral traits: walks order book ladder, returns fill metrics like top_of_book, vwap, slippage, verdicts (clean|degraded|cannot_fill), and for baskets warns about thin_legs and forced_directional_risk. Annotations (readOnlyHint, idempotentHint) align; 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?

Well-structured with bold headers for modes, front-loaded purpose, and concise sentences. Slightly verbose but all content earns its place given tool complexity. Minor redundancy ('SINGLE-MARKET:' vs later details) but overall 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?

Complete for a complex tool with no output schema: lists all return fields for both modes, explains dangers, integrates sibling tool references, and provides usage thresholds. No gaps noted.

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 significant meaning beyond the 100% schema coverage: explains side defaults per mode, size_usd interpretation (max spend vs target proceeds for single-market; settlement notional for basket), and clamps. Provides critical context for correct invocation.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool instead.

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

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

Explicitly tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why partial fills convert arb into directional risk, providing clear context for when not to skip this step.

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 readOnly/idempotent annotations by disclosing behavioral nuances: the fee model limitation, safety codes, the rule that unclassified legs are never paired, the meaning of null temporal_alignment, and the fact that pairing is keyword-based rather than source-verified. These are genuine behavioral traits that affect how the agent interprets results, and none contradict the annotations.

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

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

The description is lengthy but densely structured with labels like 'TWO MODES:', 'RESPONSE:', 'SAFETY FIELDS:', and 'Codes:' which make it scannable. It is front-loaded with the core purpose. Some redundancy exists (e.g., 'BOTH modes run the identical token-overlap matcher, so the same disclosures apply to both'), but the length is justified by the complexity of the output and edge cases.

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 carries full responsibility for explaining return values and edge cases. It does so comprehensively: response contents, top_spreads_pp, compatibility_warning/codes, temporal_alignment semantics, fees_note, skipped_cross_type/subtype, and unclassified leg handling. An agent receiving results from this tool would understand exactly what each field means and what pitfalls to check.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context about mode behavior (both modes run the same matcher, explicit parameters override topic-mapped ones), but the schema already documents each parameter with examples and override semantics. The additional value over the schema is modest, keeping the score at 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+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly differentiates the tool from siblings like polymarket_arbitrage or polymarket_edges by naming the two venues and the central concept. The purpose is unambiguous and the agent can immediately understand what this tool computes.

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

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

The description provides explicit usage context for the two modes ('TWO MODES: (1) `topic` ... (2) explicit `kalshi_event_ticker` + `polymarket_event_slug`'). It also warns about when results should be trusted ('Real cross-venue spreads are rarer than the macro-shortcut list suggests... pre-mapped ≠ tradeable'). However, it never names alternative sibling tools or says when to prefer them, so the exclusion/alternative dimension is not fully addressed.

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 important behavioral context: scoping per identifier (anonymous IP, BYO key hash, or account ID) and pairing with remember/forget. No contradictions.

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

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

Four sentences, each contributing value: action, use case, scope, pairing. Could be slightly tighter but no filler or redundancy.

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

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

No output schema exists, but description explains what is returned (value or list of keys), when to use (retrieval), and relationships to siblings. Complete for a simple read 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% and describes the single parameter 'key' as 'Memory key to retrieve (omit to list all keys)'. The description repeats this guidance but does not add new semantic meaning beyond what is in the schema.

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

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

Clearly states the action: 'Retrieve a value previously saved via remember, or list all saved keys'. Distinguishes from sibling tools 'remember' and 'forget' by naming them explicitly and describing the retrieval use case.

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

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

Provides clear context: 'to look up context the agent stored earlier... without re-deriving it from scratch'. Implies usage after 'remember' but does not explicitly state when not to use or alternatives beyond the named siblings.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate safe read. Description adds valuable context: return shape, mark_read side effect, and polling friendliness, enhancing transparency beyond annotations.

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

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

Two dense sentences efficiently convey purpose, parameters, behavior, and an alternative. Well-structured and front-loaded. Could benefit from slight restructuring but overall concise.

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

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

No output schema, but description adequately describes return shape (source, citation_uri, raw event payload) and supports polling and mark_read. Sufficient for a read-only 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%, but description adds concrete examples (e.g., 'sec_8k' for type) and clarifications (ISO timestamp for since, effect of mark_read). Provides marginal additional value over 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 'Pull fired events from your subscription feed' and lists specific returned fields (source, citation_uri, raw event payload), distinguishing it from sibling tools like list_subscriptions or search_within.

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 clear guidance on filtering (type, since), mark_read behavior, polling suitability, and even an alternative REST endpoint. Does not explicitly contrast with siblings but covers when-to-use adequately.

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 (which indicate read-only, open-world, idempotent, non-destructive), the description details internal behavior: fanning out to multiple sources, GDELT→GNews fallback, USPTO API sunset soft-failure, parameter format options, and return structure with grouped changes and citation URIs.

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 well-structured paragraph that front-loads example queries, explains every key aspect, and contains no extraneous information. Every sentence provides necessary 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 tool's complexity (multiple data sources, fallback logic, parameter formats) and lack of output schema, the description fully covers the return structure, source grouping, total_changes count, and citation URIs. It also addresses limitations like the USPTO soft-failure.

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 schema already covers all parameters with 100% coverage, the description adds significant context: it explains that type only supports 'company', gives examples for value (ticker vs. CIK), and explains the since parameter's ISO date and relative shorthand formats with recommended values.

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

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

The description clearly defines the tool as a change feed for a company covering SEC filings, news, and patents. It includes concrete query examples ('What's new with X') and explicitly distinguishes the tool from sibling tool '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?

The description provides explicit guidance on when to use this tool versus the alternative 'entity_profile' and offers specific recommendations for the 'since' parameter ('Use "30d" or "1m" for typical monitoring.').

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

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

Adds context beyond annotations: describes scoping by identifier, retention rules for authenticated vs. anonymous users, and pairs with recall/forget. Annotations already indicate idempotency and non-destructiveness, so this is complementary.

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?

Very concise: three sentences that efficiently convey purpose, usage guidance, and behavioral details. No superfluous 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?

Covers all necessary aspects for a simple key-value store: what it does, when to use, scoping, retention. Might lack explicit overwrite behavior, but idempotent hint and examples make it clear.

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

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

Schema coverage is 100% with clear descriptions. The tool description adds value by giving examples of keys and values, and explaining the memory scope, which enriches understanding beyond the schema.

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

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

The description clearly states the tool saves data for later reuse, using a key-value store. It distinguishes itself from sibling tools like 'recall' and 'forget' by explicitly mentioning them as complementary actions.

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 specific use cases (resolved ticker, target address, etc.) and context for when to use the tool. Does not explicitly state when not to use, but the examples give strong guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses substantial behavior: unresolved identifiers are listed under 'unresolved' rather than omitted, ambiguous instrument matches assert nothing and return candidates, and LEI/FIGI enrichment degrades gracefully when upstream sources are unavailable. It even explains that one call internally cascades through multiple lookup endpoints.

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 purpose statement and uses useful SUPPORTED TYPES labeling, but it is very long and dense for a two-parameter tool. Several semicolon-heavy run-on sentences pack many distinct facts together, reducing scannability even though most content is valuable.

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

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

There is no output schema, so the description must carry the burden of explaining return behavior. It covers ambiguity (figi_candidates), unresolved identifiers, source-labelled IDs, and graceful degradation, which is sufficient for an agent to know what to expect and how to handle partial resolution. Given the complexity of multi-source entity resolution, this is 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 already 100%, so the baseline is 3. The description adds meaningful extra semantics beyond the schema, notably that company input also accepts ISIN and maps it to the issuing legal entity, and that the value must be the entity name alone. Some detail duplicates the schema's value description, which prevents a 5.

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 query examples and immediately states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It specifies supported entity types ('company', 'drug') and clearly differentiates this resolver from downstream tools that consume the IDs.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies edge cases like ambiguous names returning figi_candidates and non-ticker instruments still resolving. However, it does not name sibling alternatives or state when not to use this tool versus related tools like entity_profile or compare_entities.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining the internal behavior: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. 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 very concise: three sentences that immediately convey purpose, mechanism, and use case. It is front-loaded with the most critical information, with 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?

Despite lacking an output schema, the description specifies the return format ('ranked list with score, confidence, signal density per entity'). It adequately covers the tool's functionality and context for an AI agent, though it assumes familiarity with the sibling ai_visibility_check.

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

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

Schema coverage is 100%, providing baseline 3. The description mentions 'entities' and 'models' in context but does not add semantic meaning beyond the schema descriptions. No additional parameter-level details are provided, so a 3 is appropriate.

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

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

The description clearly states the verb 'Compare AI visibility' and the resource 'multiple entities', distinguishing it from the sibling tool ai_visibility_check which likely handles single entities. It explains the aggregation and ranking process, making the purpose unmistakable.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and a realistic question, guiding when to use this tool. It implicitly suggests that for a single entity, one would use ai_visibility_check, but it does not explicitly state when not to use or list alternatives, preventing a 5.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds significant behavioral context: it fans out to external services (deps.dev and bundlephobia), notes that bundlephobia's first measurement can take 5-30 seconds, and explains how partial failures are handled gracefully with sources_failed field. 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 efficiently structured: starts with composite purpose, lists what it covers, gives usage examples, specifies ecosystem scope, and ends with failure behavior. Every sentence provides essential information with no redundancy or fluff.

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

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

Despite complexity (composite call, multiple sources, no output schema), the description thoroughly covers return fields (summary, advisories, links, alternatives), ecosystem boundary, and failure modes. It provides enough context for an AI agent to understand what to expect and how the tool behaves.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds extra context beyond schema: it notes that scoped packages (@types/node) are accepted, and clarifies that version defaults to latest. This adds modest value, justifying a score above the baseline of 3.

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

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

The description clearly states the tool performs a composite check for npm packages, answering questions about safety, popularity, and size. It explicitly distinguishes from other ecosystems (PyPI, Maven, etc.) by noting they fall under deps.dev:version directly, differentiating it from potential 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?

Provides explicit when-to-use guidance: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies the NPM-only scope and directs users to other tools for other ecosystems. Mentions graceful degradation for partial failures, indicating behavior in edge 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?

Discloses internal mechanics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation/flagging. Complements annotations (readOnlyHint, idempotentHint) with specific technical details. No contradictions.

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

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

Three sentences: first defines core function, second provides usage context and pairing, third gives technical details. Every sentence is information-dense and front-loaded. 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?

For a tool with no output schema, the description adequately explains return values (passages with offsets and scores). Covers chunking, truncation, and pairing with gateway tool. All relevant behavioral and usage aspects are addressed.

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

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

Schema coverage is 100% and the description enhances parameter understanding: the query is described as 'natural-language' with examples, limit has a default and range, and text is explained with usage context and max size.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' and details the inputs and outputs (top-N passages with offsets and scores). It distinguishes itself by focusing on searching within an already-fetched text, contrasting with external search tools among 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?

Provides clear when-to-use guidance: 'Use when the record is too big to cram into the prompt'. Explains the benefit (saves context) and the returned offsets for verification. Directly pairs with a sibling tool (ask_pipeworx_grounded) for grounding over passages.

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

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

The description adds significant behavior beyond annotations: requires OAuth account, returns subscription id, delivery channel constraints (SMS cap, webhook auto-disable, secret one-time return). Annotations only indicate non-read-only, non-destructive, idempotent, open world.

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 comprehensive but somewhat lengthy. It is well-structured with purpose first, then types, then delivery. Every sentence adds value, but could be trimmed slightly for 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?

For a create tool with no output schema, the description covers return value, prerequisites, all types and params, delivery channel behaviors, and failure modes (webhook auto-disable). Thorough and 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%. Description adds concrete examples for each type, delivery channel details (phone verification, webhook HMAC), and explains the params object structure thoroughly. Adds substantial 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 creates a proactive monitoring subscription to a live-data event stream, specifying verb, resource, and context. It distinguishes from siblings like unsubscribe and list_subscriptions.

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

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

Provides explicit when-to-use guidance with prerequisites, types, and delivery options. Lacks explicit when-not-to-use but context is clear. Does not directly contrast with pulling via recent_alerts.

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

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

Annotations already indicate read-only and non-destructive. Description adds detail about returning example questions with tool+argument shapes, and that it's an entry point with no side effects.

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

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

Description is informative but somewhat lengthy. Listing all categories is helpful but could be more concise. Well-structured with examples and usage instructions.

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

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

Complete for an onboarding tool: covers purpose, usage, parameter, output format, and when to use. No output schema, but description adequately explains return value.

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 description adds value by listing specific topic values and explaining the effect of omitting vs providing the parameter.

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

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

Clearly states it is an onboarding entry point that returns category-bucketed example questions. Distinguishes from siblings by indicating it should be used first before knowing 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 to call with no arguments for full spread or pass a topic to focus. Tells to use first when unsure. Lacks explicit when-not-to-use, but context implies alternatives.

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

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

Beyond annotations (which declare idempotent, non-destructive, non-read-only), the description adds key behavioral context: ownership enforcement, deactivation (not deletion), and preservation of history. This fully informs the agent of side effects.

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

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

Three concise sentences, each adding distinct value: core action, ownership rule, and behavioral nuance. No filler, front-loaded with the primary purpose.

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

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

For a simple one-parameter tool with annotations and no output schema, the description covers all essential aspects: what it does, constraints, and downstream effects (history remains). 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 input schema (100% coverage) describes 'id' as a UUID from subscribe. The description adds that the id must belong to the caller's own subscription, which is additional semantic context 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 specifies the verb ('Cancel'), resource ('subscription'), and method ('by id'), distinguishing it clearly from siblings like subscribe, list_subscriptions, and recent_alerts. It also clarifies that it deactivates rather than deletes.

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 states ownership enforcement ('you can only cancel your own subscriptions') and notes that deactivation keeps historical events available via recent_alerts, guiding appropriate usage. It lacks explicit when-not-to-use statements but context with siblings suffices.

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 readOnly/idempotent annotations, the description discloses the full verdict set, the critical distinction between could_not_verify and unsupported, the structured vs grounded pipeline, and the error field. The 'IMPORTANT for callers' note clarifies that could_not_verify is not evidence, which is essential behavioral context.

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

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

The description is long but every sentence contributes: it front-loads example phrasings, explains routing, defines return values, and provides error handling. No filler or repetition—each part earns its place given 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?

With no output schema, the description compensates by explaining the verdict values, the format of the actual value and citation, and the nuanced meaning of could_not_verify and unsupported. It also covers the fallback pipeline and the reasoning component, making the tool's behavior fully understandable.

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

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

While schema coverage is 100%, the description enriches both parameters: it explains tolerance_pct overrides the implied tolerance, sets 1–2 for hallucination detection, and gives the default cap. The claim parameter is illustrated with concrete examples, adding semantic depth 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 defines the tool as natural-language claim verification against authoritative sources, with example phrasings and a specific verb-resource pairing. It distinguishes coverage for company-financial vs other claims but does not explicitly name sibling alternatives for comparison.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context. It also details the two-path routing (SEC EDGAR/XBRL vs grounded pipeline) and mentions replacing sequential calls, but does not explicitly state when not to use or name alternative tools.

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