Inaturalist

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds important context: default model, optional Anthropic with BYO key and direct payment, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 entire description is concise, front-loaded with the core action and scoring, then adds secondary details (default model, apiKey, returns) in a logical order. Every sentence serves a purpose 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?

Given the tool has 4 parameters with full schema coverage, no output schema, and moderate complexity, the description fully covers usage, model options, key handling, return format, and example use cases. It leaves no major gaps for an agent to infer.

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 value beyond the schema by explaining the default model (Workers AI Llama-3.3-70b, free), the condition for _apiKey, and the disambiguation purpose of 'context'. This enriches understanding 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 the action ('probe', 'score'), the resource ('LLMs'), and the scope ('business / brand / product / topic'), with specific scoring range (0-100). It also distinguishes the tool by listing use cases like AI-marketing audits and pre-launch checks, differentiating it from sibling tools such as scan_competitor_ai_presence.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional _apiKey. However, it does not explicitly state when not to use this tool or directly compare to siblings like compare_entities or deep_research.

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

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

With annotations already covering read-only, open-world, idempotent, and non-destructive behavior, the description adds useful context, such as routing to 5,596 tools, filling arguments automatically, and exporting results with stable citation URIs. It does not fully explain failure modes or rate limits, but annotations lower the burden and it does not contradict them.

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

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

The description is longer than average because it exhaustively lists data domains, trigger phrases, examples, and routing alternatives, but most of these are useful for a broad meta-tool. It front-loads the most important instruction ('PREFER OVER WEB SEARCH') and then builds to examples and exclusion for deep_research, so it earns its length.

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

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

Given the tool only requires one free-text question, the description is enough to call it correctly: it specifies what kinds of questions are appropriate, gives examples, and describes the expected outcome (answer with pipeworx:// citations). It does not explicitly describe what happens on unsupported or non-factual queries, but for a tool of this scope the guidance 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 description coverage is 100%, and the schema already documents the single required 'question' parameter and its aliases. The description adds example questions and general domain context, but it does not meaningfully add parameter semantics beyond what the schema provides. Baseline 3 is appropriate because the schema supplies the structural detail.

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

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

The description clearly states that ask_pipeworx routes natural-language factual questions to 'the right one of 5,596 tools across 1,465 verified sources' and returns 'the structured answer with stable pipeworx:// citation URIs.' It gives explicit domains, trigger phrases, and concrete example queries, making the tool’s purpose concrete. It also differentiates from deep_research by assigning that sibling to 'broad/long-tail research questions.'

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 says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions,' and explicitly says 'Don't fall back to web search until you've tried PipeWorx.' It names deep_research as the alternative for broad/long-tail research and notes that breaking-news questions are already handled by ask_pipeworx through live news routes. This gives clear when-to-use and when-not-to-use guidance.

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

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

The description goes well beyond the read-only, idempotent, open-world annotations. It discloses the candidate-routing mechanism, the fact no candidate is currently active, and the current exact-match behavior to ask_pipeworx. It also clarifies there is no fallback behavior and that this is a full working router, not a stubbed experiment.

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

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

Every sentence in the description earns its place: it explains the beta purpose, same tool surface, current routing state, comparison use, and a clarifying guarantee about fallback behavior. It is front-loaded and avoids excessive detail.

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 enough for invoking the tool: it defines scope, current behavior, and relationship to ask_pipeworx. The only minor gap is that it relies on the reader already knowing ask_pipeworx's response shape details, but that sibling is present in the tool set and the description is still self-contained for selection and invocation.

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

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

The input schema provides full 100% coverage of all six parameters, including aliases and the accepted natural-language question field. The description adds no parameter semantics, but it does not need to because the schema already fully documents them. Baseline 3 is appropriate.

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

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

The description clearly states this is the beta version of ask_pipeworx and identifies it as an identical universal router with the same 5,596 tools, arguments, and response shape. It also explicitly frames the difference from the stable sibling: candidate routing improvements may be active under test. This gives the agent a precise, distinguishing purpose.

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

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

The description explicitly says to use it exactly like ask_pipeworx when the agent wants the newest routing, and notes that results are compared against the stable router. This provides a clear condition for choosing this tool over the main alternative.

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

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

Beyond the readOnlyHint and idempotent annotations, the description explains the critical grounding behavior: it only uses the data within the tool result, returns an explicit refusal with specific reasons, and discloses the extra LLM call cost. This gives the agent accurate expectations about the tool's refusal and accuracy characteristics.

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 focused: it opens with the core purpose, then explains the mechanism, return contract, use case, and cost tradeoff. It is longer than minimal, but each sentence carries decision-relevant information such as when to use an alternative, the refusal reasons list, and when to avoid the tool.

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

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

Given a complex orchestration-style tool with no output schema, this description provides sufficient grounding: it gives the return value shape, a taxonomy of refusal reasons, the domain context, and a policy recommendation. The only missing detail lies in parameter schema, but the input schema already covers that thoroughly.

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

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

With 100% schema description coverage, the schema already explains the question parameter and its aliases, so the description does not need to add parameter-level detail. The description adds behavioral context such as routing and argument filling, but not per-parameter semantic content.

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 defines this as a grounded answer mode: it extracts answers only from tool results and returns evidence and refusal reasons. It also distinguishes the tool from the sibling ask_pipeworx by describing the extra grounding behavior and when denial is indicated.

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 usage guidance is explicit: use when the answer will be quoted, cited, or acted on and the agent must not invent facts, with examples like financial verdicts, legal claims, medical lookups, and public statements. It also states that ask_pipeworx is preferred for casual lookups due to the cost of one extra LLM call.

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

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

The description extensively covers behavior beyond annotations, including fan-out examples, response shapes, resolver contract, parent_event extractor, news fallback mechanics, safety short-circuits for low-confidence or closed markets, tradeability warnings, and resolution-rule risk. Annotations declare readOnlyHint/openWorldHint/idempotentHint, which align with the description's emphasis on safe, non-destructive research.

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 excessively long (multiple paragraphs) and lacks clear structure. Critical information like usage guidelines appears only after detailed fan-out examples. While comprehensive, it violates conciseness: not every sentence earns its place, and key points could be front-loaded more effectively.

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 compensates by detailing response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extractor, and various edge cases (low-confidence, closed markets, wide spreads, cancellation rules). This provides sufficient context for an AI agent to understand tool behavior and parse responses correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining input types (slug, URL, question text), the depth parameter's effect (quick vs thorough), and include_raw's impact on response size. It also provides examples and elaborates on the market field's flexibility.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and outcome (evidence packet + comparison). This distinguishes it from sibling tools like polymarket_edges or validate_claim.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains market input formats. However, it could more explicitly state when to use alternative tools (e.g., polymarket_edges for pure edge iteration).

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, open-world, idempotent, and non-destructive behavior. The description adds rich behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradictions found.

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 examples and is relatively concise given the complexity. Every sentence adds information, though it could be slightly tighter. Rewards for clarity outweigh minor verbosity.

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

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

Despite lacking an output schema, the description outlines the return format (paired data plus citation URIs) and covers key behaviors (sorting, data sources). It does not discuss error cases or rate limits, but those are minor omissions for a tool with clear 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%, so the schema already defines parameters. The description adds value by explaining the meaning of each 'type' value ('company' pulls financials, 'drug' pulls FAERS data) and clarifying that 'values' expects tickers/CIKs for companies and drug names, with item limits.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs. It provides multiple query examples ('X vs Y', 'which is bigger') and distinguishes itself from sequential single-pack lookups, 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?

Explicitly advises to prefer this tool over sequential lookups when comparing entities, and gives natural language triggers. However, it does not explicitly mention when not to use it (e.g., for a single entity), though the sibling 'entity_profile' likely handles that.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description details the findings packet layout (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), guarantees gaps[] are explicit and never invented, explains hop semantics for depth levels, mentions contradictions[] scanning, and notes semantic excerpting of large records. This is rich behavioral disclosure that is not conveyed by the annotations alone.

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 dense and front-loads critical prerequisites and alternatives before the long behavioral explanation. Every sentence earns its place, but the wall-of-text paragraph with semicolons and parentheticals hurts readability. It is over-sized yet not padded, so 4 rather than 5.

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

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

The description covers prerequisites (account, paid plan), alternative selection, timeout expectations, return structure, citation semantics, gap handling, depth-dependent behaviors, and content coverage limits. For a tool with no output schema and a complex research pipeline, all necessary context is present.

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 input schema already fully documents both parameters and the depth enum. The description adds some context (account tier requirement for thorough, expected latency, how depth variants influence iteration), but it does not add significant meaning beyond the schema for the question or depth parameters themselves. The baseline of 3 is appropriate.

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

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

The description states a specific verb ('research'), a precise resource ('Pipeworx's 1465 structured data sources'), and explicitly distinguishes its scope from open-web search. It names concrete use cases and explicitly separates it from sibling tools like ask_pipeworx, making it easy for an agent to pick correctly.

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 and when-not-to-use guidance: use deep_research for broad/multi-part questions over structured data, use ask_pipeworx for single lookups or breaking live news, and use ask_pipeworx if the user is not signed in. It names the alternative tool and the exact conditions for choosing 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?

Description adds significant context beyond annotations: it specifies the tool returns top-N relevant tools with names, descriptions, and full input schemas with examples, ready to call directly. 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?

Six sentences covering purpose, usage, and behavior without redundancy. Front-loaded with key purpose. Could be slightly more concise but still effective.

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

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

Given no output schema and many siblings, the description fully explains what the tool returns and when to use it, addressing both discovery and direct usability of results.

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

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

Schema coverage is 100%, but description provides extra value by explaining query accepts natural language, lists aliases, and gives examples. This goes beyond simple parameter descriptions.

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

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

The description clearly states the verb 'Find tools' and resource 'tools', differentiated from sibling tools that search for data rather than tools themselves.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance and context for exclusion.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds detailed behavior: parallel fan-out across multiple sources, specific data returned (cik, filings with URIs, fundamentals, patents with soft-fail, news via fallback, LEI). No contradictions.

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

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

Description is dense with useful information but slightly verbose (~150 words). Front-loaded with example queries, well-structured with semicolons. Could be trimmed slightly but effective.

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

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

Given no output schema, description explains return fields (cik, filings, fundamentals, patents, news, LEI) with specifics like URIs and fallback mechanisms. Lacks exact structure of news/patents count, but adequate for understanding.

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 descriptions are clear. The description repeats schema info but adds example values and format for ticker/CIK. Marginal added 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?

Description clearly states the tool provides a full cross-source profile of a US public company in a single parallel call, listing sources and return fields. It distinguishes from siblings by stating to prefer over chaining single-pack lookups and references resolve_entity for name inputs.

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 holistic views, to prefer over chaining separate lookups, and mentions using resolve_entity first if only a name is available. Also warns about USPTO sunset. Provides clear when-to-use and alternatives.

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

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

Annotations already provide destructiveHint=true; description adds context about deleting agent-saved memories but does not go beyond annotations.

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

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

Two sentences, no unnecessary words, purpose stated first.

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 1-parameter destructive tool with full schema coverage and adequate annotations, description provides all needed context.

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

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

Schema has 100% coverage with description 'Memory key to delete'; description adds no additional meaning beyond schema.

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

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

Description clearly states verb 'Delete' and resource 'memory by key', distinguishing it from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use ('context stale, task done, clear sensitive data') and suggests pairing with 'remember' and 'recall'.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds specific behavioral details: fetches the page, extracts title/description/key links, emits standard markdown. It doesn't contradict annotations and provides useful context beyond them.

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

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

The description is three sentences, front-loaded with purpose, followed by process and use cases. Every sentence adds value with no redundancy or excess.

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 two-parameter tool with no output schema and strong annotations, the description explains the output format (standard llms.txt markdown blob). It could mention error handling or accessibility constraints, but overall it is sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions default max_links (25) and max (50), which is also in schema. No additional semantic information beyond what the schema provides.

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

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

The description uses specific verbs and resources: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes this tool from siblings by focusing on generating the llms.txt standard file, which is unique among the listed 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 provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor visibility. While it doesn't explicitly state when not to use it, the use cases are clear and no close sibling exists for generating llms.txt.

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 safety and idempotency; description adds that it lists 'active' subscriptions by default and specifies returned fields, but lacks details on pagination or rate limits.

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

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

Two concise sentences with no redundant information; the main action is front-loaded.

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

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

For a simple list tool with one optional parameter and strong annotations, the description fully covers purpose, usage, and return fields.

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 description indirectly clarifies the parameter's behavior by stating 'active subscriptions,' helping the agent understand the default without explicit parameter description.

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

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

The description clearly states the verb 'list' and the resource 'subscriptions', and distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on retrieval.

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

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

Explicitly tells the agent to use this to review existing subscriptions before adding more or to find an ID to cancel, providing clear when-to-use guidance.

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

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

Annotations are all false, so the description carries full burden. It discloses rate-limiting (5 per identifier per day), that it's free and doesn't count against tool-call quota, that filing without an account returns a claim_token, and that the team reads digests daily. This goes well beyond what annotations provide, though it doesn't explicitly state the side effect of creating a stored feedback record (which is implied by 'tell the team').

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 runs ~200 words, longer than typical, but nearly every sentence serves a purpose: purpose, exclusions, claim_token workflow, and rate limits. It is front-loaded with the core purpose and then handles edge cases. No fluff, though it could be tightened slightly by merging the rate-limit and free-quota sentences.

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

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

This tool has 4 optional params and no output schema, so the description must cover the touchpoints. It thoroughly explains the claim_token return value, how to use it later, rate limiting, and the scope of what the team can fix. It also provides message-length guidance (1-2 sentences, 2000 chars max). Complete for an agent to know exactly how to invoke it and what to expect.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaningful extra guidance: it explains how to describe issues in terms of Pipeworx tools/packs (not pasting end-user prompts), and details the claim_token round-trip usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'). This goes beyond the schema's per-field descriptions, meriting a 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes it from sibling tools like ask_pipeworx (querying) and discover_tools (exploration). The purpose is unmistakable.

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

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

Provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise) and a firm exclusion: only for tools served by this Pipeworx connection, not other MCP servers. Also explains the claim_token workflow for checking resolution, leaving no ambiguity about when to use each parameter.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds further transparency: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This communicates safety, data source, and caching behavior, exceeding the annotation baseline.

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

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

Description is concise (three sentences), well-structured, and front-loaded with the main function. Every sentence adds value with no redundant or extraneous 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?

Tool has one optional parameter and no output schema, but description fully covers returned data (top tools, top packs, total call volume) and caching behavior. For its simplicity, the description is complete without gaps.

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

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

The single parameter 'window' has full schema coverage with enum and description. The description adds semantic value: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides meaningful interpretation beyond the raw schema.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a recent window. The verb 'returns' and resource specification are precise, and the tool's purpose (trending/popularity) distinguishes it from siblings like discover_tools or top_species.

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 three explicit use cases (discovering hot data sources, confirming popular tool, aligning use case) and explains the significance of window options. While it lacks explicit 'when not to use' or alternative tool names, the use cases offer strong positive guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description goes further by explaining internal logic: walks child markets, checks date-axis/threshold-axis ordering, computes partition_sum, applies Jaccard similarity filter (≥0.30), filters placeholder slugs, and performs fill check against live CLOB depth. No contradictions.

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

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

The description is well-organized with sections for each mode and sub-sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the main purpose and modes. However, it is slightly verbose with implementation details that could be condensed, but still effective.

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

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

Given the tool's complexity (multiple modes, filters, and trade signals), the description covers all necessary aspects: input modes, output structure (opportunities[] with fields), fill-check logic, and limitations. It also references a related tool for custom sizing, making it 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 parameter descriptions. The tool's description adds context: recommends event for specific markets, topic for cross-event scanning, and notes that full Polymarket URLs are accepted. It enhances understanding beyond the schema alone.

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

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

The description clearly defines the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three distinct call modes (no args, event, topic) and distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also warns when not to trade (realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing.

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

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

Annotations are supplemented with extensive behavioral details: caching (1h at KV level), response structure with diagnostics, edge calculation formulas, slippage handling, and exclusion of certain bets. No contradictions with annotations.

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

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

The description is lengthy but front-loaded with purpose. Every sentence adds value for an agent, but some technical formula details could be simplified without loss of clarity.

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

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

Given 9 parameters, no output schema, and rich annotations, the description covers caching, return structure, edge sources, filtering knobs, and diagnostics, making it fully complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context beyond schema, such as explaining 'Tradeable-edge filter' for max_spread_pp and min_liquidity, and clarifying that min_kelly applies to single-leg opportunities while min_partition_leg_kelly applies to partition legs.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and positions it for 'what should I bet on today'. This provides a specific verb+resource+goal that distinguishes it from sibling tools like polymarket_arbitrage.

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

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

Description explains the tool's role in discovery without paging, details tradeable-edge knobs for filtering, and notes Fed bets are excluded. However, it does not explicitly name alternative tools or state when not to use this one.

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, idempotent, non-destructive. The description adds significant behavioral details: explains the response structure (tracked[], expired[], snapshot_dates[]), how decay is computed, and limitations like 60-day TTL and daily snapshots. No contradiction with annotations.

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

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

The description is well-organized, starting with purpose, then arguments, then detailed response structure. It is appropriately sized for the tool's complexity, though some of the response details could be slightly more concise.

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

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

Given no output schema, the description fully explains the return format: three arrays with detailed fields for each (tracked edges with time-series, expired edges with lifespan, snapshot dates). It also covers limitations (60-day TTL, daily close data) and edge cases (gaps in snapshots). Comprehensive for a complex tool.

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

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

Schema coverage is 100% with both parameters already well-described (defaults, clamps, enums for window). The description merely restates this information (e.g., 'days (lookback, default 14, max 30)') without adding new meaning or usage guidance beyond the schema.

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

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

Description clearly states the tool's purpose: tracking edge persistence and decay over time. It uses specific verbs ('answers how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical telemetry rather than current edges.

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

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

The description provides a clear use case (assessing whether an edge is decaying) and contrasts with fresh vs. old edges. However, it does not explicitly state when not to use this tool or name alternative tools for different scenarios, such as using polymarket_edges for current edge data.

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

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

Annotations declare readOnlyHint, idempotentHint, etc. The description adds extensive behavioral details: how it walks the ladder, what fields it returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), and important warnings about partial fills. No contradictions.

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

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

The description is well-structured with clear sections for single-market and basket modes, and key points in caps. It is front-loaded with purpose. However, it is somewhat long and could be slightly more concise without losing clarity.

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

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

Given the complexity (two modes, many return fields, no output schema), the description is highly complete. It details all returned fields, explains the verdict, warns about thin legs and directional risk, and covers both use cases thoroughly.

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

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

Schema coverage is 100% (all parameters have descriptions). The description adds significant meaning beyond the schema, e.g., explaining size_usd interpretation in single-market vs basket mode, default values, and behavior of side auto-selection in basket mode. This goes well 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's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It specifies the verb (check) and resource (edge), and distinguishes from siblings like polymarket_arbitrage and polymarket_edges by explaining when this tool should be used.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns about when not to skip it (e.g., partial basket fills convert arb into directional position), providing clear context and alternatives.

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

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

Annotations already mark the tool as read-only/idempotent, but the description adds extensive behavioral detail: two modes, response structure (leg-by-leg prices, spreads), safety fields (compatibility_warning, temporal_alignment, skipped counters), and scenarios where spreads are meaningless. No contradiction with annotations.

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

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

The description is thorough and well-structured, starting with the core purpose and then detailing modes, response, and safety fields. However, some sentences are dense; could be slightly more concise without losing 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 3 optional parameters and no output schema, the description is remarkably complete. It covers invocation, interpretation of results (including edge cases like incompatible bet shapes or temporal misalignment), and the statistics provided (skipped counters). No gaps identified.

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 by listing the 10 topic values, explaining how explicit tickers override topic mapping, and clarifying the optional nature of parameters. This adds significant meaning beyond the schema.

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

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

The description clearly identifies the tool as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question, distinguishing it from single-venue tools like polymarket_arbitrage. It specifies two modes (topic shortcuts and explicit tickers) and the resource being compared.

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 find cross-venue spreads) and warns that most pre-mapped topics return compatibility warnings, implying limited tradeability. It does not explicitly state when not to use it or list alternatives, but provides enough context for appropriate use.

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

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

Annotations indicate readOnlyHint, idempotentHint, destructiveHint. Description adds scoping details (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, which goes beyond annotations. No contradiction.

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

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

Three sentences, each with a purpose: first states core action, second gives usage context, third adds scoping and related tools. No unnecessary words.

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

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

Tool is simple (1 optional param, no output schema). Description covers use cases, scoping, and sibling relationships. No gaps.

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

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

Schema coverage is 100%; baseline 3. Description adds meaning by explaining behavior when key is omitted (list all keys), which is not fully captured in the schema's parameter description.

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

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

Clearly states the verb 'retrieve' and resource 'value previously saved via remember', and distinguishes by explaining omitting key lists all keys. Distinguishes from siblings remember and forget.

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

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

Provides context for when to use: 'look up context the agent stored earlier... without re-deriving it from scratch.' Mentions scoping and pairing with remember/forget. Lacks explicit when-not, 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 declare readOnlyHint=true, implying no state modification, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which clearly modifies state. This is a direct contradiction. The description also fails to disclose other behaviors like rate limits or auth requirements.

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

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

The description is relatively concise with about five sentences, front-loading the core purpose. It uses clear language and avoids unnecessary verbiage. Minor redundancy exists (e.g., 'Polls work fine' could be more precise), but overall it is well-structured.

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

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

Given the tool has 5 parameters, no output schema, and annotations provide some context, the description covers return fields, parameter usage, and an alternative access method. It does not address error handling or pagination, but the information provided is sufficient for basic 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%, and the description adds value beyond schema descriptions by providing examples (e.g., 'sec_8k' for type) and explaining the effect of 'mark_read' on subsequent calls. It does not repeat all schema details, but the added context is helpful.

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

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

The description starts with a clear verb+resource: 'Pull fired events from your subscription feed.' It specifies the return fields (source, citation_uri, raw event payload) and filtering options, making the purpose very specific and actionable. While it doesn't explicitly distinguish from siblings, the purpose is unambiguous.

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

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

The description provides guidance on filtering and the 'mark_read' parameter, and mentions an alternative HTTP endpoint for scripts. However, it does not explicitly advise when to use this tool versus sibling tools like 'list_subscriptions' or 'subscribe', nor does it state conditions where the tool should not be used.

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

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

Beyond annotations (readOnly, idempotent, not destructive), the description details fan-out to multiple sources, fallback behavior (GNews when GDELT rate-limited), and soft-failures (PatentsView API sunset). It also describes return structure.

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

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

The description is somewhat lengthy but every sentence adds unique value. It opens with common query patterns and then explains mechanics. Could be slightly more structured, but it is efficient and informative.

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

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

Given the complexity (three sources, fallback, single call), the description covers what the tool does, return shape (changes grouped by source), limitations (soft-fail on USPTO), and entity type constraint. No output schema, but return structure is described.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining shorthand for 'since' (e.g., '7d', '3m'), suggesting typical monitoring values, and clarifying that 'type' only supports 'company'.

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

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

The description clearly states the tool returns a change feed for a company, combining SEC filings, GDELT/GNews news, and patents. It provides specific query examples and distinguishes from sibling '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 explicitly advises when to use this tool vs entity_profile, and gives guidance on the 'since' parameter (e.g., 'use 30d or 1m for typical monitoring'). No explicit when-not-to-use beyond the single sibling alternative.

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

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

Description adds value beyond annotations: key-value scoped by identifier, persistence differences for authenticated vs anonymous users (24h). No contradiction with annotations.

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

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

Four sentences, each serving a purpose: action, usage trigger, scoping/persistence, complementary tools. No waste.

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

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

Given no output schema, description explains storage behavior, scoping, and persistence. It adequately prepares the agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline 3. Description adds context by explaining key-value storage and scoping, which helps understanding parameter usage.

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

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

The description clearly states 'Save data the agent will need to reuse later' with specific verb 'Save' and resource 'data'. It distinguishes from siblings like recall and forget by mentioning them explicitly.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward' and provides examples. Also advises pairing with recall/forget for complete memory lifecycle.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: graceful degradation of LEI/FIGI enrichment, explicit statement of unresolved identifiers under an 'unresolved' field, source-labelling of identifiers, and cascading internal lookups. No contradictions with annotations.

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

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

The description is informative but verbose, containing lengthy technical details about identity spine, data sources, and enrichment processes. While structured and front-loaded with examples, it could be more concise for an agent to quickly parse. The extra detail is not strictly necessary for correct invocation.

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

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

The description covers return behavior (labelled identifiers, unresolved list, graceful degradation) and input varieties. Without an output schema, it provides enough detail for an agent to understand what the tool returns. However, it could be more explicit about the exact output structure or fields.

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

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

Both parameters have schema descriptions (100% coverage), but the description adds meaningful context: it explains that 'type' can be 'company' or 'drug' with detailed enrichment behavior, and for 'value' it lists accepted input formats (ticker, CIK, ISIN, or name) with examples. This goes beyond the schema's basic descriptions.

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

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

The description starts with specific query examples like 'What's the ticker for…' and clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from siblings by being the primary tool for name-to-ID resolution and lists supported entity types.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to invoke this tool. It also notes that it replaces 2-3 manual lookups, encouraging use over alternative approaches. However, it does not explicitly exclude any scenarios or mention when not to use it.

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

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

Beyond the safe annotations (readOnlyHint, idempotentHint), the description reveals that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This provides significant behavioral insight 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?

The description is two sentences, front-loading the purpose in the first sentence and adding mechanism and use case in the second. Every sentence is meaningful 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?

The description covers what the tool does, how it works internally, and what it returns. While it omits exact constraints (e.g., entity count 2-8) and error handling, these are covered by the schema and the description is sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds value by explaining that the first entity is treated as the 'subject' for narrative purposes and that context disambiguates common names. This enriches understanding beyond the raw 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 compares AI visibility across multiple entities side-by-side, explicitly referencing the sibling tool ai_visibility_check for individual probes. It distinguishes itself from single-entity checks and explains the competitive audit use case.

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and implies when to use over ai_visibility_check (single vs multiple). However, it does not explicitly state when not to use or list alternatives beyond the implicit reference.

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, destructiveHint. Description adds behavioral details: fans out to two services, partial failures degrade gracefully, Bundlephobia first measurement can take 5-30s, sources_failed lists timeouts. These go beyond annotations to set accurate expectations.

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 longer but well-structured: starts with purpose, then usage guidelines, then behavioral notes. Every sentence adds value, though could be slightly more concise without losing clarity.

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

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

Despite no output schema, description fully specifies return fields (summary block, per-advisory detail, links, alternative versions), ecosystem limitations, and error handling. Covers all necessary context for an agent to understand inputs, outputs, and edge cases.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds that version defaults to latest when omitted and scoped packages like @types/node are accepted, supplementing 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 the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia data. It specifies resources (npm package) and action (scan), and distinguishes from siblings by being the only tool dedicated to dependency analysis.

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

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

Provides explicit when-to-use guidance: 'when an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also states when NOT to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', clearly differentiating from alternatives.

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

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

Annotations already declare readOnlyHint=true, etc. Description adds that results are 'photographed sightings with coordinates, dates, and observer info' and that place auto-resolves to place_id. No harmful behavior, but adds useful context beyond annotations.

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

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

Single paragraph front-loads purpose and then details filters and return fields. While slightly dense, every sentence adds value and the description is efficient for the information conveyed.

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 output schema present and annotations covering safety, the description provides all essential usage details: filters, return fields, and cross-validation hint. No gaps remain for an agent to use this tool effectively.

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 examples of taxon names (common and scientific), clarifies that place auto-resolves, and lists filterable criteria in a narrative form, providing extra value over the schema alone.

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

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

Description explicitly states verb ('Search'), resource ('citizen-science wildlife observations on iNaturalist'), and scope ('ANY organism'). Provides examples of filterable criteria and contrasts with sibling tool GBIF, making 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?

Gives a clear usage pattern ('sightings/observations of <species> in <place> in <year>') and suggests pairing with GBIF. However, does not explicitly state when not to use or compare with sibling tool 'search_taxa'.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds return field details but no behavioral traits beyond what annotations provide.

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

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

Two sentences, front-loaded with action and return fields, no waste. Every word adds value.

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

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

Covers purpose, return format, and downstream usage. Output schema exists for detail, and parameters are fully described in the schema. No gaps identified.

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 parameters. The description does not add additional meaning beyond what is in the schema, so baseline score of 3 applies.

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

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

The description clearly states the tool searches iNaturalist taxa by name (common or scientific), lists specific return fields, and distinguishes it from other tools like search_observations by mentioning downstream use of taxon ID.

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

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

Provides explicit guidance on using the taxon ID for downstream filters or disambiguation, but does not mention when not to use this tool or direct alternatives among 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds significant behavioral details: embedding model (BGE-base-en), cosine over 500-char windows, 200K char cap with truncation flag, and every passage carries offset for verification. 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 about 6-7 sentences, well-structured with the core purpose upfront. Each sentence adds unique information without redundancy. Could trim minor details but still efficient.

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

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

With no output schema, the description adequately explains the output (passages with offsets, similarity scores). It covers internal mechanics, limitations (char cap), and pairing with a sibling tool. Slightly more could be said about error scenarios, but overall complete for the complexity.

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

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

Schema coverage is 100% with descriptions for all three parameters. Description enhances meaning by explaining the purpose of each parameter (e.g., 'Natural-language query'), default values, and constraints (max chars for text). Adds value beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying input (text and query) and output (passages with offsets and scores). It distinguishes from siblings by naming ask_pipeworx_grounded and explaining when to use this tool over alternatives.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefits (saves context, returns only relevant passages). It pairs with a sibling tool, providing integration guidance. No explicit when-not-to-use, 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?

The description discloses important behavioral traits beyond annotations: persistence requirement (anonymous/BYO cannot persist), delivery constraints (SMS 10/day cap, webhook auto-disabled after 10 failures), and response including subscription id. It does not contradict annotations (readOnlyHint=false, idempotentHint=true).

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 slightly long. It is well-structured with line breaks and grouping by subscription type, and front-loaded with the main action. Every sentence adds value, but some redundancy (e.g., repeated phone verification note) could be trimmed.

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

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

Given the complexity (5 subscription types, 3 delivery channels, constraints, and authentication requirements), the description is thorough. It explains the return value and covers all critical aspects for correct agent invocation, making it complete for a tool without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by providing type-specific examples (items:['5.02'], topic:'fed', series_id:'UNRATE') and detailed delivery configurations (webhook signing, phone verification). This extra context improves parameter 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 uses a specific verb ('Create') and resource ('proactive monitoring subscription'), and clearly states the return value ('Returns the new subscription id'). It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context on when to use this tool (to set up monitoring subscriptions) and prerequisites ('Requires a Pipeworx OAuth account'). It details supported types and delivery channels, guiding the agent on appropriate usage, though it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds that it returns category-bucketed example questions with tool and argument shapes, which is useful behavioral context beyond the annotations.

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

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

The description is thorough but slightly long; however every sentence serves a purpose. It is front-loaded with common questions and structured logically from overview to usage 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?

The description fully covers the tool's purpose, when to use it, what it returns, and how to call it. Given no output schema, the description explains the return format sufficiently.

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 a baseline of 3. The description adds value by explaining that omitting the topic gives 'full spread' and passing a focus topic narrows results, which is more semantic than the schema's brief description.

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

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

The description clearly states it is the onboarding entry point for an agent to learn what Pipeworx can do. It uses specific verb phrases like 'What can I ask Pipeworx?' and lists example topics, distinguishing it from siblings such as ask_pipeworx and discover_tools.

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

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

Explicitly says to use this FIRST when you do not know what Pipeworx can do, or to learn how to call meta-tools. Also provides guidance on invoking with no arguments for full spread or with a specific topic.

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

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

Annotations already mark it as read-only and idempotent. Description adds that place auto-resolves to ID, which is useful behavioral context beyond annotations.

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

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

Two concise sentences without fluff, 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?

Despite simplicity, description covers purpose, behavior, and usage. Output schema exists, so no need to detail return values.

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

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

Schema has 100% coverage with basic descriptions. Description adds that place auto-resolves to place_id and per_page is 1-50 with default 20, enhancing understanding.

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

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

Description clearly states the tool retrieves most-frequently-observed species in a place over a date range, auto-resolves place names, and returns ranked data. Distinct from siblings like search_observations.

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 suggests use for 'what wildlife lives here?' questions, implying when to use. Could improve by mentioning when not to use or naming 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?

Describes deactivation (not deletion) and preservation of historical events, adding behavioral context beyond annotations. Also clarifies ownership enforcement.

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

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

Two sentences, no wasted words, front-loaded with the core action.

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

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

For a single-parameter tool with no output schema, description covers ownership, effect (deactivation), and relation to historical data. Complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds that 'id' is the subscription id from subscribe, but schema already describes it.

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 verb 'cancel' and resource 'subscription by id'. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('only cancel your own subscriptions'), guiding when to use. Does not explicitly mention alternatives, but context is clear.

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

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

While annotations already mark the tool as read-only, idempotent, and open-world, the description adds critical behavioral details: specific verdict types, the meaning of 'could_not_verify' with its error object, and the distinction between 'unsupported' and 'refuted'. It also warns that 'could_not_verify' must not be presented as evidence, which is a crucial misuse-avoidance trait.

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

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

The description is longer than typical but every sentence adds value: trigger phrases, usage guidance, dual-path behavior, return semantics, and error handling. It is well-structured with clear transitions, though slightly verbose; the density of important information justifies the length.

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

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

With no output schema, the description fully covers return values (verdict types), error cases, and the reasons for outcomes. It also explains the fast vs. grounded paths and how the tool replaces multiple sequential steps, making it complete for an agent to invoke correctly without external context.

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

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

The schema already provides full descriptions for both parameters (100% coverage), but the description enriches them by explaining how tolerance_pct interacts with claim wording, the default cap of 5, and its use for hallucination detection. This added context goes beyond the schema's basic descriptions, though the schema already carries significant weight.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with explicit trigger phrases. It distinguishes itself from siblings by covering both a structured SEC EDGAR path and a grounded pipeline, and notes it replaces 4-6 sequential calls, making its unique role obvious.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates between company-financial claims and other factual claims. It also implies when not to use it by contrasting with the sequential alternative, providing clear context for tool selection.

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